Expand description
rutis: Cordis 核心范式的 Rust 惯用实现。
五支柱(设计文档 §一):
- 插件 = 装配单元(一次
apply,提供服务/监听/清理) - fiber = 生命周期容器(六态状态机 + 依赖门控 + 级联卸载 + 恰好一次清理)
- 服务 = 类型键注册表 + isolate 作用域
- 事件总线 = 四分发语义(emit/parallel/serial/waterfall)
- 依赖驱动重载(provider 卸载 → 消费者驱逐并自动重载)
Structs§
- Binding
Diagnostics - Ctx
- 上下文 =
Arc<CtxInner>(所有权模型:Clone 廉价;isolate/plugin 返回共享内核的新 Ctx)。 - DepKey
- A service key whose value type is
T: every constructor namesT, so a key cannot point at a service of another type. - Dependency
Diagnostics - Dispatch
Attempt - A dispatch before its business listener snapshot is selected. An observed instance attempt can still lose a race with subtree shutdown and be rejected.
- Disposer
- 清理句柄(D28):仅表示提前释放,不需要也不应再放回
Effect; drop 不触发清理(fiber 卸载仍兜底)。 - Effect
Meta - Read-only cleanup ownership tree. Child phases follow their owning record; the tree does not track which individual leaf is currently executing.
- Event
Backlog - The
emits of one event key that were accepted and have not finished. Same-key emits are dispatched one after another, so a slow listener holds up the ones behind it;emititself never waits for them. - Event
Bus - Typed event bus: four async dispatch modes, plus synchronous bail/waterfall.
- Event
Key - A channel whose payload and result types are fixed by
E. - Event
Options on()/on_waterfall()注册选项(§四偏差清单:prepend 保留,影响 serial/waterfall 结果)。- Event
Pattern - One registration matching any of its prefixes, within one event type. Only named channels without an instance can match. An empty prefix matches every such channel; overlapping prefixes still select the registration once.
- Event
Subscription - A current registration, without retaining its callback or fiber.
- Fiber
Status Changed - fiber 状态迁移事件(D24:锁内 FIFO 入队、锁外分发;
seq保证提交顺序可识别,不保证 listener 完成顺序)。 - Fiber
View - fiber 句柄:注册返回,
IntoFuture= 等待进入稳定态(启动错误经 Err 返回)。 - Gate
- Gates the plugin on
TypeKey::of::<T>()without passing the service. - Instance
Id - A process-local fiber identity. IDs are never reused, including after shutdown.
- Key
- 类型化限定名常量(开放问题 2 的裁决:
Key<T>newtype,shaku Keyed 精神)。 - Keyed
- A required service found under a
DepKey. - Keyed
Gate - Gates the plugin on a
DepKeywithout passing the service. - Next
- 类型化续延句柄,交给
WaterfallListener。零参调用(TS waterfall 语义: 事件载荷固定,值经返回值向上流动),M1 定稿(见 §八)。 - Plugin
Diagnostics - Plugin
Id - 插件身份(D10:注册返回的显式 id,非闭包指针)。
- Resolved
Dependency - Runtime
Diagnostics - A read-only, best-effort view of live fibers and service bindings.
- Service
Access - Service
Changed - A service binding was registered or finally removed. Emitted on the bus of the provider’s context, after the registry change and outside every lock. A registered binding becomes visible once its provider is active; removal is reported after consumers were evicted.
- Service
Read Error - A strict read error with the key, caller identity, and source location.
- Service
Write Error - A mutable service update error with the original binding identity.
- Service
Writer - Generation-bound authority to update one mutable service binding.
- Snapshot
- fiber 快照(watch 载荷,generation 兼作 sequence,D24)。
- Sync
Next - Single-use, borrowed continuation. It preserves the input event and passes the downstream value back to its caller.
- TypeKey
- 服务键 = TypeId + 可选限定名(D21:
ServiceKey = TypeKey)。 D33:限定名放宽为双轨,支持运行时构造的名字(桥事件等); 代价是失去Copy——克隆装载/注册路径,频率低。 携带构造时捕获的类型名,仅用于诊断(describe/错误消息); 相等与哈希由 TypeId、限定名和实例号决定；类型名只供诊断。 - Typed
- A
TypedPluginas aPlugin:ctx.plugin(Typed::new(plugin)). - Typed
Factory - A
TypedPluginFactoryas aPluginFactory:ctx.plugin_with(TypedFactory::new(factory), config).
Enums§
- Cordis
Error - 框架错误。不
Clone(D11);跨任务共享走Arc<CordisError>。 - Dependency
Status - Dispatch
Mode - Which public dispatch operation produced an observation.
- Dispose
Wait Error - 等待卸载的结果。超时只结束本次等待；驱动继续执行清理，再次调用
dispose()会 join 同一任务。同步代码若不让出执行权，Tokio 无法 强制中断，deadline 也无法在该 runtime 线程上及时触发。 - Effect
- 插件装配交回的清理(D18:清理可报错;闭包捕获 owned
Ctx,不传&Ctx)。 - Effect
Phase - Whether an owned cleanup record is waiting or currently being drained.
- Fiber
State - 六态状态机(§四:保留 TS 六态)。
- Listener
Kind - The callback family of a registered listener.
- Service
Change - Service
Intercept - A trusted interceptor can continue, replace a same-type value, or deny an
operation. The type alone cannot prove which instance created
Arc<T>. - Service
Read Failure - Why a strict service read was rejected. Optional
getreads do not use this check. - Service
Write Failure - Why a provider-owned mutable service update was rejected.
Traits§
- Deps
- A set of dependencies read from a context.
- Event
- 类型化事件(D16)。
NAME仅日志诊断,不参与唯一性与分发;Value是 serial 短路值类型(裁决开放问题 2)。 - Listener
- 监听器统一形状(D16:helper trait 解决 alias 的 E0106)。
- Pattern
Listener - A grouped prefix listener also receives the actual matching channel key.
- Pattern
Waterfall Listener - Plugin
- 插件 = 装配单元(支柱 1)。config 烘进实例(D19):
具体插件在
new(config)时持有配置,validate校验自持那份。 - Plugin
Factory - 插件工厂(D32:配置热更新):每代从当前 config 构造插件实例。
- Sync
Event - Opt in to synchronous dispatch. Async dispatch remains available for this type, through separate async registrations.
- Sync
Listener - Sync
Pattern Listener - Sync
Pattern Waterfall Listener - Sync
Waterfall Listener - Terminal
- waterfall 终态续延(D17):由调用方提供的兜底行为,不与事件并列。
- Typed
Plugin - A plugin whose dependencies are a type. Mount it with
Typed. - Typed
Plugin Factory - A factory of typed plugins (configuration hot update). Mount it with
TypedFactory; the declaration comes fromPlugin::Deps, as forTyped, and every built plugin reads with the same keys. - Waterfall
Listener - waterfall 监听器(D17:独立注册面,显式接收
Next续延)。
Type Aliases§
- BoxFuture
- dyn 兼容的 future 别名(与
futures::future::BoxFuture同一定义,D1)。 - Error
Sink - 错误汇聚点。默认实现输出到 stderr(设计 §二)。
- Service
Key - 服务键别名(D21 裁决:
ServiceKey不另建类型)。