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)]
24pub struct PluginVTable<StartArgs, Instance> {
25    pub plugin_version: &'static str,
26    pub plugin_long_version: &'static str,
27    pub start: StartFn<StartArgs, Instance>,
28}
29
30impl<StartArgs, Instance> PluginVTable<StartArgs, Instance> {
31    pub fn new<ConcretePlugin: Plugin<StartArgs = StartArgs, Instance = Instance>>() -> Self {
32        Self {
33            plugin_version: ConcretePlugin::PLUGIN_VERSION,
34            plugin_long_version: ConcretePlugin::PLUGIN_LONG_VERSION,
35            start: ConcretePlugin::start,
36        }
37    }
38}
39
40/// This macro adds non-mangled functions which provides plugin version and loads it into the host.
41/// If plugin library should work also as static, consider calling this macro under feature condition
42///
43/// The functions declared by this macro are:
44///
45/// - `get_plugin_loader_version` - returns `PLUGIN_LOADER_VERSION` const of the crate. The [`PluginsManager`](crate::manager::PluginsManager)
46///   will check if this version is compatible with the host.
47/// - `get_compatibility` - returns [`Compatibility`](crate::Compatibility) struct which contains all version information (Rust compiler version, features used, version of plugin's structures).
48///   The layout  of this structure is guaranteed to be stable until the [`PLUGIN_LOADER_VERSION`](crate::PLUGIN_LOADER_VERSION) is changed,
49///   so it's safe to use it in the host after call to `get_plugin_loader_version` returns compatible version.
50///   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.
51/// - `load_plugin` - returns [`PluginVTable`](crate::PluginVTable) which is able to create plugin's instance.
52///
53#[macro_export]
54macro_rules! declare_plugin {
55    ($ty: path) => {
56        #[no_mangle]
57        fn get_plugin_loader_version() -> $crate::PluginLoaderVersion {
58            $crate::PLUGIN_LOADER_VERSION
59        }
60
61        #[no_mangle]
62        fn get_compatibility() -> $crate::Compatibility {
63            use zenoh_plugin_trait::StructVersion;
64            $crate::Compatibility::new(
65                <$ty as $crate::Plugin>::StartArgs::struct_version(),
66                <$ty as $crate::Plugin>::StartArgs::struct_features(),
67            )
68        }
69
70        #[no_mangle]
71        fn load_plugin() -> $crate::PluginVTable<
72            <$ty as $crate::Plugin>::StartArgs,
73            <$ty as $crate::Plugin>::Instance,
74        > {
75            $crate::PluginVTable::new::<$ty>()
76        }
77    };
78}
zenoh_plugin_trait/vtable.rs

zenoh_plugin_trait/
vtable.rs
