Module

Core trait for all iii framework modules

The Module trait is the foundation for all modules in the iii framework. Every module must implement this trait to integrate with the engine’s lifecycle management, function registration, and background task execution.

Location

use iii::modules::module::Module;

Defined in src/modules/module.rs

Trait Definition

#[async_trait::async_trait]
pub trait Module: Send + Sync {
    fn name(&self) -> &'static str;
    
    async fn create(
        engine: Arc<Engine>,
        config: Option<Value>
    ) -> anyhow::Result<Box<dyn Module>>
    where
        Self: Sized;
    
    fn make_module(
        engine: Arc<Engine>,
        config: Option<Value>
    ) -> ModuleFuture
    where
        Self: Sized + 'static;
    
    async fn initialize(&self) -> anyhow::Result<()>;
    
    async fn start_background_tasks(
        &self,
        _shutdown: tokio::sync::watch::Receiver<bool>,
    ) -> anyhow::Result<()>;
    
    async fn destroy(&self) -> anyhow::Result<()>;
    
    fn register_functions(&self, engine: Arc<Engine>);
}

Required Methods

name

fn name(&self) -> &'static str

Returns the static name of the module.

return · &'static str

The module’s name identifier

create

async fn create(
    engine: Arc<Engine>,
    config: Option<Value>
) -> anyhow::Result<Box<dyn Module>>

Creates a new instance of the module. This is the primary constructor method.

engine · Arc<Engine> · required

Reference to the iii engine instance

config · Option<Value>

Optional JSON configuration for the module

return · anyhow::Result<Box<dyn Module>>

Returns a boxed module instance or an error

initialize

async fn initialize(&self) -> anyhow::Result<()>

Initializes the module. Called after creation and before the module is used.

return · anyhow::Result<()>

Returns Ok(()) on success or an error

Optional Methods

make_module

fn make_module(
    engine: Arc<Engine>,
    config: Option<Value>
) -> ModuleFuture

Helper method to create a module future. Has a default implementation that calls create.

engine · Arc<Engine> · required

Reference to the iii engine instance

config · Option<Value>

Optional JSON configuration for the module

return · ModuleFuture

A pinned future that resolves to a module instance

start_background_tasks

async fn start_background_tasks(
    &self,
    _shutdown: tokio::sync::watch::Receiver<bool>,
) -> anyhow::Result<()>

Starts any background tasks required by the module. Default implementation does nothing.

shutdown · tokio::sync::watch::Receiver<bool> · required

Shutdown signal receiver to gracefully stop background tasks

return · anyhow::Result<()>

Returns Ok(()) on success or an error

destroy

async fn destroy(&self) -> anyhow::Result<()>

Cleans up module resources during shutdown. Default implementation logs and returns Ok.

return · anyhow::Result<()>

Returns Ok(()) on success or an error

register_functions

fn register_functions(&self, engine: Arc<Engine>)

Registers the module’s functions with the engine. Usually overridden by the #[service] macro.

engine · Arc<Engine> · required

Reference to the iii engine instance for function registration

Implementation Example

use std::sync::Arc;
use async_trait::async_trait;
use serde_json::Value;
use iii::{
    engine::Engine,
    modules::module::Module,
};

#[derive(Clone)]
pub struct KvServer {
    storage: Arc<BuiltinKvStore>,
}

#[async_trait]
impl Module for KvServer {
    fn name(&self) -> &'static str {
        "KV Server"
    }

    async fn create(
        _engine: Arc<Engine>,
        config: Option<Value>,
    ) -> anyhow::Result<Box<dyn Module>> {
        let storage = BuiltinKvStore::new(config);
        let storage = Arc::new(storage);
        Ok(Box::new(KvServer { storage }))
    }

    fn register_functions(&self, engine: Arc<Engine>) {
        // Usually generated by #[service] macro
        self.register_functions(engine);
    }

    async fn initialize(&self) -> anyhow::Result<()> {
        Ok(())
    }
}

Related Types

ModuleFuture

type ModuleFuture = Pin<Box<dyn Future<Output = anyhow::Result<Box<dyn Module>>> + Send>>;

A pinned boxed future that resolves to a Module instance.

See Also

• QueueAdapter - Trait for queue adapters
• StreamAdapter - Trait for stream adapters
• Custom Modules - Guide to building custom modules