Update Plugin descriptionpost-merge/api-readme-fixes

Signed-off-by: Matthias Beyer <matthias.beyer@ifm.com>

1 files 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.
 
 -------