Define a trait for Plugins and allow them to be dynamically loaded or statically linked

Cargo.toml

@@ -17,6 +17,7 @@ members = [
   "zenoh",
   "zenoh-util",
   "zenoh-ext",
+  "plugins/zenoh-plugin-trait",
   "plugins/example-plugin",
   "plugins/zenoh-plugin-rest",
   "plugins/zenoh-plugin-storages",

plugins/example-plugin/Cargo.toml

@@ -14,10 +14,12 @@
 [package]
 name = "zplugin-example"
 version = "0.5.0-dev"
-authors = ["kydos <angelo@icorsaro.net>",
-           "Julien Enoch <julien@enoch.fr>",
-           "Olivier Hécart <olivier.hecart@adlinktech.com>",
-		   "Luca Cominardi <luca.cominardi@adlinktech.com>"]
+authors = [
+    "kydos <angelo@icorsaro.net>",
+    "Julien Enoch <julien@enoch.fr>",
+    "Olivier Hécart <olivier.hecart@adlinktech.com>",
+    "Luca Cominardi <luca.cominardi@adlinktech.com>",
+]
 edition = "2018"
 
 # NOTE: as this library name doesn't start with 'zplugin_' prefix
@@ -29,7 +31,9 @@ crate-type = ["cdylib"]
 
 
 [dependencies]
-zenoh = { path = "../../zenoh" }
+zenoh = { path="../../zenoh" }
+zenoh-util = { path="../../zenoh-util" }
+zenoh-plugin-trait = { path="../zenoh-plugin-trait" }
 futures = "0.3.12"
 clap = "2"
 log = "0.4"

plugins/example-plugin/src/lib.rs

@@ -19,24 +19,69 @@ use futures::select;
 use log::{debug, info};
 use runtime::Runtime;
 use std::collections::HashMap;
+use std::sync::{
+    atomic::{AtomicBool, Ordering::Relaxed},
+    Arc,
+};
 use zenoh::net::queryable::STORAGE;
 use zenoh::net::utils::resource_name;
 use zenoh::net::*;
+use zenoh_plugin_trait::prelude::*;
+use zenoh_util::zerror2;
 
-#[no_mangle]
-pub fn get_expected_args<'a, 'b>() -> Vec<Arg<'a, 'b>> {
-    vec![
-        Arg::from_usage("--storage-selector 'The selection of resources to be stored'")
-            .default_value("/demo/example/**"),
-    ]
+pub struct ExamplePlugin {
+    selector: ResKey,
 }
 
-#[no_mangle]
-pub fn start(runtime: Runtime, args: &'static ArgMatches<'_>) {
-    async_std::task::spawn(run(runtime, args));
+zenoh_plugin_trait::declare_plugin!(ExamplePlugin);
+
+pub struct ExamplePluginStopper {
+    flag: Arc<AtomicBool>,
+}
+
+impl PluginStopper for ExamplePluginStopper {
+    fn stop(self) {
+        self.flag.store(false, Relaxed);
+    }
+}
+
+impl Plugin for ExamplePlugin {
+    fn compatibility() -> zenoh_plugin_trait::Compatibility {
+        zenoh_plugin_trait::Compatibility {
+            uid: "zenoh-example-plugin",
+        }
+    }
+
+    fn get_expected_args() -> Vec<Arg<'static, 'static>> {
+        vec![
+            Arg::from_usage("--storage-selector 'The selection of resources to be stored'")
+                .default_value("/demo/example/**"),
+        ]
+    }
+
+    fn init(args: &ArgMatches) -> Result<Self, Box<dyn std::error::Error>> {
+        if let Some(selector) = args.value_of("storage-selector") {
+            Ok(ExamplePlugin {
+                selector: selector.into(),
+            })
+        } else {
+            Err(Box::new(zerror2!(ZErrorKind::Other {
+                descr: "storage-selector is a mandatory option for ExamplePlugin".into()
+            })))
+        }
+    }
+}
+
+impl PluginLaunch for ExamplePlugin {
+    fn start(self, runtime: Runtime) -> Box<dyn PluginStopper> {
+        let flag = Arc::new(AtomicBool::new(true));
+        let stopper = ExamplePluginStopper { flag: flag.clone() };
+        async_std::task::spawn(run(runtime, self.selector, flag));
+        Box::new(stopper)
+    }
 }
 
-async fn run(runtime: Runtime, args: &'static ArgMatches<'_>) {
+async fn run(runtime: Runtime, selector: ResKey, flag: Arc<AtomicBool>) {
     env_logger::init();
 
     let session = Session::init(runtime, true, vec![], vec![]).await;
@@ -49,7 +94,6 @@ async fn run(runtime: Runtime, args: &'static ArgMatches<'_>) {
         period: None,
     };
 
-    let selector: ResKey = args.value_of("storage-selector").unwrap().into();
     debug!("Run example-plugin with storage-selector={}", selector);
 
     debug!("Declaring Subscriber on {}", selector);
@@ -61,7 +105,7 @@ async fn run(runtime: Runtime, args: &'static ArgMatches<'_>) {
     debug!("Declaring Queryable on {}", selector);
     let mut queryable = session.declare_queryable(&selector, STORAGE).await.unwrap();
 
-    loop {
+    while flag.load(Relaxed) {
         select!(
             sample = sub.receiver().next().fuse() => {
                 let sample = sample.unwrap();

plugins/zenoh-plugin-trait/Cargo.toml

@@ -0,0 +1,35 @@
+#
+# Copyright (c) 2017, 2020 ADLINK Technology Inc.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+# which is available at https://www.apache.org/licenses/LICENSE-2.0.
+#
+# SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+#
+# Contributors:
+#   ADLINK zenoh team, <zenoh@adlink-labs.tech>
+#
+[package]
+name = "zenoh-plugin-trait"
+version = "0.1.0-dev"
+authors = [
+    "kydos <angelo@icorsaro.net>",
+    "Julien Enoch <julien@enoch.fr>",
+    "Olivier Hécart <olivier.hecart@adlinktech.com>",
+    "Luca Cominardi <luca.cominardi@adlinktech.com>",
+    "Pierre Avital <pierre.avital@adlinktech.com>",
+]
+edition = "2018"
+
+[lib]
+name = "zenoh_plugin_trait"
+
+[features]
+no_mangle = []
+default = ["no_mangle"]
+
+[dependencies]
+zenoh = { path="../../zenoh" }
+clap = "2"

plugins/zenoh-plugin-trait/src/lib.rs

@@ -0,0 +1,205 @@
+//
+// Copyright (c) 2017, 2020 ADLINK Technology Inc.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+//
+// Contributors:
+//   ADLINK zenoh team, <zenoh@adlink-labs.tech>
+//
+
+//! # The plugin infrastructure for Zenoh.
+//!
+//! To build a plugin, up to 2 types may be constructed :
+//! * A [Plugin] type.
+//! * [PluginLaunch::start] should be non-blocking, and return a boxed instance of your stoppage type, which should implement [PluginStopper].
+
+use clap::{Arg, ArgMatches};
+use std::error::Error;
+use zenoh::net::runtime::Runtime;
+
+pub mod prelude {
+    pub use crate::{dynamic_loading::*, Plugin, PluginLaunch, PluginStopper};
+}
+
+/// Your plugin's compatibility.
+/// Currently, this should simply be the plugin crate's name.
+/// This structure may evolve to include more detailed information.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Compatibility {
+    pub uid: &'static str,
+}
+
+#[derive(Clone)]
+pub struct Incompatibility {
+    pub own_compatibility: Compatibility,
+    pub conflicting_with: Compatibility,
+    pub details: Option<String>,
+}
+
+/// Zenoh plugins must implement [Plugin] and [PluginLaunch]
+pub trait Plugin: PluginLaunch + Sized + 'static {
+    /// Returns this plugin's [Compatibility].
+    fn compatibility() -> Compatibility;
+
+    /// As Zenoh instanciates plugins, it will append their [Compatibility] to an array.
+    /// This array's current state will be shown to the next plugin.
+    ///
+    /// To signal that your plugin is incompatible with a previously instanciated plugin, return `Err`,
+    /// Otherwise, return `Ok(Self::compatibility())`.
+    ///
+    /// By default, a plugin is non-reentrant to avoir reinstanciation if its dlib is accessible despite it already being statically linked.
+    fn is_compatible_with(others: &[Compatibility]) -> Result<Compatibility, Incompatibility> {
+        let own_compatibility = Self::compatibility();
+        if others.iter().any(|c| c == &own_compatibility) {
+            let conflicting_with = own_compatibility.clone();
+            Err(Incompatibility {
+                own_compatibility,
+                conflicting_with,
+                details: None,
+            })
+        } else {
+            Ok(own_compatibility)
+        }
+    }
+
+    /// Returns the arguments that are required for the plugin's construction
+    fn get_expected_args() -> Vec<Arg<'static, 'static>>;
+
+    /// Constructs an instance of the plugin, which will be launched with [PluginLaunch::start]
+    fn init(args: &ArgMatches) -> Result<Self, Box<dyn Error>>;
+
+    fn box_init(args: &ArgMatches) -> Result<Box<dyn PluginLaunch>, Box<dyn Error>> {
+        match Self::init(args) {
+            Ok(v) => Ok(Box::new(v)),
+            Err(e) => Err(e),
+        }
+    }
+}
+
+/// Allows a [Plugin] instance to be started.
+pub trait PluginLaunch {
+    fn start(self, runtime: Runtime) -> Box<dyn PluginStopper>;
+}
+
+/// Allows a [Plugin] instance to be stopped.
+/// Typically, you can achieve this using a one-shot channel or an [AtomicBool](std::sync::atomic::AtomicBool).
+/// If you don't want a stopping mechanism, you can use `()` as your [PluginStopper].
+pub trait PluginStopper {
+    fn stop(self);
+}
+
+impl PluginStopper for () {
+    fn stop(self) {}
+}
+
+pub mod dynamic_loading {
+    use super::*;
+    pub use no_mangle::*;
+
+    type InitFn = fn(&ArgMatches) -> Result<Box<dyn PluginLaunch>, Box<dyn Error>>;
+    pub type PluginVTableVersion = u16;
+
+    /// This number should change any time the internal structure of [PluginVTable] changes
+    pub const PLUGIN_VTABLE_VERSION: PluginVTableVersion = 0;
+
+    #[repr(C)]
+    struct PluginVTableInner {
+        init: InitFn,
+        is_compatible_with: fn(&[Compatibility]) -> Result<Compatibility, Incompatibility>,
+        get_expected_args: fn() -> Vec<Arg<'static, 'static>>,
+    }
+
+    /// Automagical padding such that [PluginVTable::init]'s result is the size of a cache line
+    #[repr(C)]
+    struct PluginVTablePadding {
+        __padding: [u8; PADDING_LENGTH],
+    }
+    const PADDING_LENGTH: usize =
+        64 - std::mem::size_of::<Result<PluginVTableInner, PluginVTableVersion>>();
+    impl PluginVTablePadding {
+        fn new() -> Self {
+            PluginVTablePadding {
+                __padding: [0; PADDING_LENGTH],
+            }
+        }
+    }
+
+    /// For use with dynamically loaded plugins. Its size will not change accross versions, but its internal structure might.
+    ///
+    /// To ensure compatibility, its size and alignment must allow `size_of::<Result<PluginVTable, PluginVTableVersion>>() == 64` (one cache line).
+    #[repr(C)]
+    pub struct PluginVTable {
+        inner: PluginVTableInner,
+        padding: PluginVTablePadding,
+    }
+
+    impl PluginVTable {
+        pub fn new<ConcretePlugin: Plugin + 'static>() -> Self {
+            PluginVTable {
+                inner: PluginVTableInner {
+                    is_compatible_with: ConcretePlugin::is_compatible_with,
+                    get_expected_args: ConcretePlugin::get_expected_args,
+                    init: ConcretePlugin::box_init,
+                },
+                padding: PluginVTablePadding::new(),
+            }
+        }
+
+        /// Ensures [PluginVTable]'s size stays the same between versions
+        fn __size_check() {
+            unsafe {
+                std::mem::transmute::<_, [u8; 64]>(std::mem::MaybeUninit::<
+                    Result<Self, PluginVTableVersion>,
+                >::uninit())
+            };
+        }
+
+        pub fn is_compatible_with(
+            &self,
+            others: &[Compatibility],
+        ) -> Result<Compatibility, Incompatibility> {
+            (self.inner.is_compatible_with)(others)
+        }
+
+        pub fn get_expected_args(&self) -> Vec<Arg<'static, 'static>> {
+            (self.inner.get_expected_args)()
+        }
+
+        pub fn init(&self, args: &ArgMatches) -> Result<Box<dyn PluginLaunch>, Box<dyn Error>> {
+            (self.inner.init)(args)
+        }
+    }
+
+    pub use no_mangle::*;
+    #[cfg(feature = "no_mangle")]
+    pub mod no_mangle {
+        /// This macro will add a non-mangled `load_plugin` function to the library if feature `no_mangle` is enabled (which it is by default).
+        #[macro_export]
+        macro_rules! declare_plugin {
+            ($ty: path) => {
+                #[no_mangle]
+                fn load_plugin(
+                    version: PluginVTableVersion,
+                ) -> Result<PluginVTable, PluginVTableVersion> {
+                    if version == PLUGIN_VTABLE_VERSION {
+                        Ok(PluginVTable::new::<$ty>())
+                    } else {
+                        Err(PLUGIN_VTABLE_VERSION)
+                    }
+                }
+            };
+        }
+    }
+    #[cfg(not(feature = "no_mangle"))]
+    pub mod no_mangle {
+        #[macro_export]
+        macro_rules! declare_plugin {
+            ($ty: path) => {};
+        }
+    }
+}