Trait Plugin 

pub trait Plugin:
    Any
    + Send
    + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn on_mail(&self, event: &Event);

    // Provided methods
    fn deps(&self) -> &[&str] { ... }
    fn routes(&self) -> Vec<Cow<'static, str>> { ... }
    fn mailbox_cap(&self) -> usize { ... }
    fn version(&self) -> Cow<'static, str> { ... }
    fn as_configurable(&self) -> Option<&dyn Configurable> { ... }
    fn services(&self) -> Vec<ServiceDesc> { ... }
    fn on_init(&self, _ctx: &PluginContext) { ... }
    fn on_start(&self) { ... }
    fn on_stop(&self) { ... }
}

Required Methods

fn name(&self) -> &str

注册键(D2 校验)。

fn on_mail(&self, event: &Event)

★ 唯一业务入口:永远在本插件 worker 线程上串行执行。 广播事件、寻址请求(eReq.<本名>)、定向通知(eTo.<本名>)都从这里进。

Provided Methods

fn deps(&self) -> &[&str]

D1 显式依赖清单(宿主注册期校验存在性,start 期拓扑排序)。

fn routes(&self) -> Vec<Cow<'static, str>>

订阅的 type 集合:广播 type(如业务常量 “eTick.”)、 自身的寻址 type(e_req_type(本名)/e_to_type(本名))。 宿主 start() 装配 forwarder → 邮箱 → on_mail。

fn mailbox_cap(&self) -> usize

邮箱容量覆写(D5:按插件可小可大,默认 MAILBOX_CAP)。

fn version(&self) -> Cow<'static, str>

插件版本(约定填 crate 版本)。默认空串 = 「未知版本」。

⚠ 陷阱(审核 F6):默认实现无法用 env!(CARGO_PKG_VERSION) —— 该宏在 ek-core 定义处展开,填出的是 ek-core 的版本。 插件侧必须显式覆写:

fn version(&self) -> Cow<'static, str> {
    Cow::Borrowed(env!("CARGO_PKG_VERSION"))
}

fn as_configurable(&self) -> Option<&dyn Configurable>

配置托底可选能力(ek-core 0.4.0,BD-CFG):有配置面的插件覆写返回 Some(self);缺省 None = 「无配置面」,宿主探查一行事、视而不见 (存量插件零改动零运行时负担)。

返回值是同一对象借出的第二张脸(&dyn Configurable),不是新实例: 宿主在 add_plugin/start 两处调用,调用期借用、借完即还,宿主只留存 ns 字符串进配置目录。&'static 不需要——生命周期就到本借用结束。

fn services(&self) -> Vec<ServiceDesc>

服务目录自报(纯声明):只在 add_plugin 时被宿主读取一次抽 id 织入路由索引; 之后 ctx.services_of/find_service/ask_service 需要明细时由宿主现场调用本方法取。

铁律(审核 F8):本方法必须纯/静态/无锁/不阻塞 —— 它会在宿主管理线程上被 与插件 worker 并发调用;违反此纪律后果自负。

目录改版铁律(执行期 DV4 发现):插件目录随配置/状态变化时,必须 先更新本方法返回的内容,再 ctx.publish_services(…) 申报 —— 宿主现场取,先申报后换内容会造成 live 细节与索引脱节。

fn on_init(&self, _ctx: &PluginContext)

可选:启动前纯接线(缓存 ctx、读配置)。禁止在此 put/注册 handler(规范)。

fn on_start(&self)

start() 按依赖拓扑序调用(只一次)。

fn on_stop(&self)

close/remove 按逆依赖序调用;调用后保证不再收到邮件。

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors