zenoh_plugin_trait/
vtable.rs

1//
2// Copyright (c) 2023 ZettaScale Technology
3//
4// This program and the accompanying materials are made available under the
5// terms of the Eclipse Public License 2.0 which is available at
6// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
7// which is available at https://www.apache.org/licenses/LICENSE-2.0.
8//
9// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
10//
11// Contributors:
12//   ZettaScale Zenoh Team, <zenoh@zettascale.tech>
13//
14use zenoh_result::ZResult;
15
16use crate::Plugin;
17
18pub type PluginLoaderVersion = u64;
19pub const PLUGIN_LOADER_VERSION: PluginLoaderVersion = 2;
20
21type StartFn<StartArgs, Instance> = fn(&str, &StartArgs) -> ZResult<Instance>;
22
23#[repr(C)]
24#[derive(Debug)]
25pub struct PluginVTable<StartArgs, Instance> {
26    pub plugin_version: &'static str,
27    pub plugin_long_version: &'static str,
28    pub start: StartFn<StartArgs, Instance>,
29}
30
31impl<StartArgs, Instance> PluginVTable<StartArgs, Instance> {
32    pub fn new<ConcretePlugin: Plugin<StartArgs = StartArgs, Instance = Instance>>() -> Self {
33        Self {
34            plugin_version: ConcretePlugin::PLUGIN_VERSION,
35            plugin_long_version: ConcretePlugin::PLUGIN_LONG_VERSION,
36            start: ConcretePlugin::start,
37        }
38    }
39}
40
41/// This macro adds non-mangled functions which provides plugin version and loads it into the host.
42/// If plugin library should work also as static, consider calling this macro under feature condition
43///
44/// The functions declared by this macro are:
45///
46/// - `get_plugin_loader_version` - returns `PLUGIN_LOADER_VERSION` const of the crate. The [`PluginsManager`](crate::manager::PluginsManager)
47///   will check if this version is compatible with the host.
48/// - `get_compatibility` - returns [`Compatibility`](crate::Compatibility) struct which contains all version information (Rust compiler version, features used, version of plugin's structures).
49///   The layout  of this structure is guaranteed to be stable until the [`PLUGIN_LOADER_VERSION`](crate::PLUGIN_LOADER_VERSION) is changed,
50///   so it's safe to use it in the host after call to `get_plugin_loader_version` returns compatible version.
51///   Then the [`PluginsManager`](crate::manager::PluginsManager) compares the returned [`Compatibility`](crate::Compatibility) with it's own and decides if it can continue loading the plugin.
52/// - `load_plugin` - returns [`PluginVTable`](crate::PluginVTable) which is able to create plugin's instance.
53///
54#[macro_export]
55macro_rules! declare_plugin {
56    ($ty: path) => {
57        #[no_mangle]
58        fn get_plugin_loader_version() -> $crate::PluginLoaderVersion {
59            $crate::PLUGIN_LOADER_VERSION
60        }
61
62        #[no_mangle]
63        fn get_compatibility() -> $crate::Compatibility {
64            use zenoh_plugin_trait::StructVersion;
65            $crate::Compatibility::new(
66                <$ty as $crate::Plugin>::StartArgs::struct_version(),
67                <$ty as $crate::Plugin>::StartArgs::struct_features(),
68            )
69        }
70
71        #[no_mangle]
72        fn load_plugin() -> $crate::PluginVTable<
73            <$ty as $crate::Plugin>::StartArgs,
74            <$ty as $crate::Plugin>::Instance,
75        > {
76            $crate::PluginVTable::new::<$ty>()
77        }
78    };
79}
zenoh_plugin_trait/vtable.rs

zenoh_plugin_trait/
vtable.rs
