diff options
author | Marcel Müller <m.mueller@ifm.com> | 2022-04-13 09:53:55 +0200 |
---|---|---|
committer | Marcel Müller <m.mueller@ifm.com> | 2022-04-13 09:53:55 +0200 |
commit | cb823b72c1c64646db4cbc4d4631b9d3885efb3c (patch) | |
tree | c5efb53f5815b8744c6f660e88bb44d05859e28f | |
parent | 8697a6e1e1b579d606b7c07e7fbde54adc6a71af (diff) |
Adapt names with documentation to be more fitting
Signed-off-by: Marcel Müller <m.mueller@ifm.com>
-rw-r--r-- | crates/core/tedge_api/examples/heartbeat.rs | 16 | ||||
-rw-r--r-- | crates/core/tedge_api/src/address.rs | 31 | ||||
-rw-r--r-- | crates/core/tedge_api/src/lib.rs | 2 | ||||
-rw-r--r-- | crates/core/tedge_api/src/message.rs | 2 | ||||
-rw-r--r-- | crates/core/tedge_api/src/plugin.rs | 46 |
5 files changed, 66 insertions, 31 deletions
diff --git a/crates/core/tedge_api/examples/heartbeat.rs b/crates/core/tedge_api/examples/heartbeat.rs index cb05b4b1..35ac183d 100644 --- a/crates/core/tedge_api/examples/heartbeat.rs +++ b/crates/core/tedge_api/examples/heartbeat.rs @@ -9,7 +9,7 @@ use futures::FutureExt; use tedge_api::{ address::ReplySender, message::NoReply, - plugin::{BuiltPlugin, Handle, HandleTypes, Message, PluginDeclaration, PluginExt}, + plugin::{BuiltPlugin, Handle, Message, PluginDeclaration, PluginExt}, Address, CancellationToken, Plugin, PluginBuilder, PluginConfiguration, PluginDirectory, PluginError, }; @@ -45,7 +45,7 @@ impl<PD: PluginDirectory> PluginBuilder<PD> for HeartbeatServiceBuilder { where Self: Sized, { - HandleTypes::empty() + HeartbeatService::get_handled_types() } async fn verify_configuration( @@ -79,7 +79,7 @@ impl<PD: PluginDirectory> PluginBuilder<PD> for HeartbeatServiceBuilder { monitored_services, cancellation_token, ) - .into_untyped()) + .finish()) } } @@ -109,7 +109,7 @@ impl Plugin for HeartbeatService { /// /// Because this example is _simple_, we do not spawn a background task that periodically sends /// the heartbeat. In a real world scenario, that background task would be started here. - async fn setup(&mut self) -> Result<(), PluginError> { + async fn start(&mut self) -> Result<(), PluginError> { println!( "HeartbeatService: Setting up heartbeat service with interval: {:?}!", self.interval_duration @@ -230,7 +230,7 @@ impl<PD: PluginDirectory> PluginBuilder<PD> for CriticalServiceBuilder { Ok(CriticalService { status: tokio::sync::Mutex::new(true), } - .into_untyped()) + .finish()) } } @@ -271,7 +271,7 @@ impl PluginDeclaration for CriticalService { /// Because the CriticalService is of course a Plugin, it needs an implementation for that as well. #[async_trait] impl Plugin for CriticalService { - async fn setup(&mut self) -> Result<(), PluginError> { + async fn start(&mut self) -> Result<(), PluginError> { println!("CriticalService: Setting up critical service!"); Ok(()) } @@ -420,8 +420,8 @@ async fn main() { let mut heartbeat = build_heartbeat_plugin(&mut comms, cancel_token.child_token()).await; let mut critical_service = build_critical_plugin(&mut comms, cancel_token.child_token()).await; - heartbeat.plugin_mut().setup().await.unwrap(); - critical_service.plugin_mut().setup().await.unwrap(); + heartbeat.plugin_mut().start().await.unwrap(); + critical_service.plugin_mut().start().await.unwrap(); let mut recv = comms .plugins diff --git a/crates/core/tedge_api/src/address.rs b/crates/core/tedge_api/src/address.rs index 38fdfa8b..1e498199 100644 --- a/crates/core/tedge_api/src/address.rs +++ b/crates/core/tedge_api/src/address.rs @@ -157,9 +157,36 @@ pub trait ReceiverBundle: Send + 'static { #[doc(hidden)] pub trait Contains<M: Message> {} -/// Declare a set of messages to be a "MessageBundle" +/// Declare a set of messages to be a [`ReceiverBundle`] which is then used with an [`Address`] to +/// specify which kind of messages a given recipient plugin has to support. /// -/// This macro can be used by a plugin author to declare a set of messages to be a `MessageBundle`. +/// The list of messages MUST be a subset of the messages the plugin behind `Address` supports. +/// +/// ## Example +/// +/// ```rust +/// # use tedge_api::{Message, make_receiver_bundle, message::NoReply}; +/// +/// #[derive(Debug)] +/// struct IntMessage(u8); +/// +/// impl Message for IntMessage { +/// type Reply = NoReply; +/// } +/// +/// #[derive(Debug)] +/// struct StatusMessage(String); +/// +/// impl Message for StatusMessage { +/// type Reply = NoReply; +/// } +/// +/// make_receiver_bundle!(struct MessageReceiver(IntMessage, StatusMessage)); +/// +/// // or if you want to export it +/// +/// make_receiver_bundle!(pub struct AnotherMessageReceiver(IntMessage, StatusMessage)); +/// ``` #[macro_export] macro_rules! make_receiver_bundle { ($pu:vis struct $name:ident($($msg:ty),+)) => { diff --git a/crates/core/tedge_api/src/lib.rs b/crates/core/tedge_api/src/lib.rs index 477bc779..3ebb4a20 100644 --- a/crates/core/tedge_api/src/lib.rs +++ b/crates/core/tedge_api/src/lib.rs @@ -11,7 +11,7 @@ /// All the parts required to write a plugin pub mod plugin; -pub use plugin::{Plugin, PluginBuilder, PluginConfiguration, PluginDirectory, PluginExt}; +pub use plugin::{Message, Plugin, PluginBuilder, PluginConfiguration, PluginDirectory, PluginExt}; /// Addresses allow plugins to exchange messages pub mod address; diff --git a/crates/core/tedge_api/src/message.rs b/crates/core/tedge_api/src/message.rs index 5b980d7b..decb41e5 100644 --- a/crates/core/tedge_api/src/message.rs +++ b/crates/core/tedge_api/src/message.rs @@ -1,7 +1,7 @@ use crate::plugin::Message; #[derive(Debug)] -/// A message which cannot be constructed and thus cannot be used to reply with +/// A message which cannot be constructed and thus can be used when no reply is expected. pub enum NoReply {} impl Message for NoReply { diff --git a/crates/core/tedge_api/src/plugin.rs b/crates/core/tedge_api/src/plugin.rs index 96c630be..b538d7fc 100644 --- a/crates/core/tedge_api/src/plugin.rs +++ b/crates/core/tedge_api/src/plugin.rs @@ -40,7 +40,7 @@ pub trait PluginDirectory: Send + Sync { /// /// ## Also see /// - /// - [`make_message_bundle`] On how to define your own named message bundle + /// - [`make_receiver_bundle`](crate::make_receiver_bundle) On how to define your own named message bundle fn get_address_for<RB: ReceiverBundle>( &self, name: &str, @@ -91,7 +91,8 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static { /// This function must return a `HandleTypes` object which represents the types of messages /// that a plugin is able to handle. /// - /// To create an instance of this type, you must use the [`HandleTypes::get_handlers_for`] method. + /// To create an instance of this type, you must call the [`PluginExt::get_handled_types`] + /// method on the plugin this PluginBuilder will build /// /// # Example /// @@ -108,7 +109,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static { /// struct MyPlugin; // + some impl Plugin for MyPlugin /// # #[async_trait::async_trait] /// # impl Plugin for MyPlugin { - /// # async fn setup(&mut self) -> Result<(), PluginError> { + /// # async fn start(&mut self) -> Result<(), PluginError> { /// # unimplemented!() /// # } /// # async fn shutdown(&mut self) -> Result<(), PluginError> { @@ -192,7 +193,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static { /// /// This function is called by the core of thin-edge to create a new plugin instance. /// - /// The `PluginExt::into_untyped()` function can be used to make any `Plugin` implementing type + /// The [`PluginExt::finish()`] function can be used to make any type implementing [`Plugin`] /// into a `BuiltPlugin`, which the function requires to be returned (see example below). /// /// # Note @@ -220,7 +221,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static { /// struct MyPlugin; // + some impl Plugin for MyPlugin /// # #[async_trait::async_trait] /// # impl Plugin for MyPlugin { - /// # async fn setup(&mut self) -> Result<(), tedge_api::error::PluginError> { + /// # async fn start(&mut self) -> Result<(), tedge_api::error::PluginError> { /// # unimplemented!() /// # } /// # async fn shutdown(&mut self) -> Result<(), tedge_api::error::PluginError> { @@ -257,7 +258,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static { /// { /// use tedge_api::plugin::PluginExt; /// let p = MyPlugin {}; - /// Ok(p.into_untyped()) + /// Ok(p.finish()) /// } /// // other trait functions... /// # fn kind_name() -> &'static str { @@ -293,14 +294,14 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static { /// If a plugin also would like to receive messages, the author of a plugin must also implement the /// `Handle` trait. /// -/// The functionality implemented via the `Plugin` trait is used to setup the plugin before +/// The functionality implemented via the `Plugin` trait is used to start the plugin before /// messages are sent to it, and to shut the plugin down when thin-edge stops operation. /// -/// The `Plugin::setup` function would be the place where a plugin author would create background +/// The [`Plugin::start`] function would be the place where a plugin author would create background /// tasks, if their plugin must send messages pro-actively. #[async_trait] pub trait Plugin: Sync + Send + DowncastSync { - /// The plugin can set itself up here + /// The plugin can start itself here /// /// This function will be called by the core of thin-edge before any message-passing starts. /// The plugin is free to for example spawn up background tasks here. @@ -377,7 +378,7 @@ impl HandleTypes { /// # use tedge_api::{Address, CoreMessages, error::DirectoryError, address::ReceiverBundle}; /// # #[async_trait::async_trait] /// # impl tedge_api::Plugin for HeartbeatPlugin { - /// # async fn setup(&mut self) -> Result<(), PluginError> { + /// # async fn start(&mut self) -> Result<(), PluginError> { /// # unimplemented!() /// # } /// # @@ -409,12 +410,6 @@ impl HandleTypes { { HandleTypes(P::HandledMessages::get_ids()) } - - /// Empty list of types. A plugin that does not handle anything will not be able to receive - /// messages except through replies sent with [`Reply`](crate::address::Reply) - pub fn empty() -> HandleTypes { - HandleTypes(Vec::with_capacity(0)) - } } impl From<HandleTypes> for HashSet<(&'static str, TypeId)> { @@ -427,6 +422,11 @@ impl From<HandleTypes> for HashSet<(&'static str, TypeId)> { /// /// This trait is a marker trait for all types that can be used as messages which can be send /// between plugins in thin-edge. +/// +/// ## Note +/// +/// A message without the expectation of a reply can use the [`NoReply`](crate::message::NoReply) +/// type. pub trait Message: 'static + Send + std::fmt::Debug { type Reply: Message; } @@ -447,15 +447,20 @@ pub trait MessageBundle { pub trait PluginExt: PluginDeclaration { /// Convert a `Plugin` into a `BuiltPlugin` /// - /// This function is only available if the Plugin is able to handle messages that are inside - /// the specified `MessageBundle`. - fn into_untyped(self) -> BuiltPlugin + /// This is used in the [`PluginBuilder::instantiate`] method to convert a struct implementing + /// `Plugin + PluginDeclaration` to a generic struct that the core of ThinEdge can then handle. + /// + /// This function is only available if the Plugin is able to handle messages that are specified + /// in [`PluginDeclaration::HandledMessages`]. + fn finish(self) -> BuiltPlugin where Self: DoesHandle<Self::HandledMessages> + Sized, { self.into_built_plugin() } + /// Get the list of types that are handled by this [`Plugin`] as specified in the + /// [`PluginDeclaration`] fn get_handled_types() -> HandleTypes where Self: DoesHandle<Self::HandledMessages> + Sized, @@ -479,6 +484,8 @@ pub struct BuiltPlugin { } impl BuiltPlugin { + /// THIS IS PART OF THE PRIVATE API DO NOT USE + #[doc(hidden)] pub fn new(plugin: Box<dyn Plugin>, handler: PluginHandlerFn) -> Self { Self { plugin, handler } } @@ -507,6 +514,7 @@ impl BuiltPlugin { } } +/// THIS IS PART OF THE PRIVATE API DO NOT USE #[doc(hidden)] pub trait DoesHandle<M: MessageBundle> { fn into_built_plugin(self) -> BuiltPlugin; |