From 3251fd55ccca2fc7bb0bdd983c68cac8366dfe34 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 21 Jun 2022 16:58:08 +0200 Subject: Update Plugin description Signed-off-by: Matthias Beyer --- crates/core/tedge_api/goals.md | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/crates/core/tedge_api/goals.md b/crates/core/tedge_api/goals.md index cb36f686..17b46464 100644 --- a/crates/core/tedge_api/goals.md +++ b/crates/core/tedge_api/goals.md @@ -384,27 +384,44 @@ Things of note here: `Plugin` is defined as follows: ```rust -/// A functionality extension to ThinEdge #[async_trait] -pub trait Plugin: Sync + Send { - /// The plugin can set itself up here - async fn setup(&mut self) -> Result<(), PluginError>; +pub trait Plugin: Sync + Send + DowncastSync { + /// 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. + async fn start(&mut self) -> Result<(), PluginError> { + Ok(()) + } - /// Handle a message specific to this plugin - async fn handle_message(&self, message: Message) -> Result<(), PluginError>; + /// The main function of the plugin + /// + /// This method is called once all plugins have [`start`](Plugin::start)ed. The plugin is free + /// to spawn new tasks or loop indefinitely (while still observing the cancel token!) + async fn main(&self) -> Result<(), PluginError> { + Ok(()) + } /// Gracefully handle shutdown - async fn shutdown(&mut self) -> Result<(), PluginError>; + /// + /// This function is called by the core of thin-edge before the software shuts down as a whole, + /// giving the plugin the opportunity to clear up resources (e.g. deallocate file handles + /// cleanly, shut down network connections properly, etc...). + async fn shutdown(&mut self) -> Result<(), PluginError> { + Ok(()) + } } ``` Plugins follow a straightforward lifecycle: -- After being instantiated the plugin will have a chance to set itself up and get ready to accept messages -- It will then continuously receive messages as they come in -- If it ever needs to be shutdown, its shutdown method will give it the opportunity to do so. - -See `message::Message` for possible values. +- After being instantiated the plugin will have a chance to set itself up and + get ready to accept messages. +- Once the plugin is started, its main loop will be called. The plugin can spawn + main loops in this function, for example if it needs to listen to external + servicse. +- If it ever needs to be shutdown, its shutdown method will give it the + opportunity to do so. ------- -- cgit v1.2.3