maiko/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! # Maiko
3//!
4//! A lightweight actor runtime for Tokio with topic-based pub/sub routing.
5//!
6//! Maiko provides independent actors that communicate through asynchronous events -no shared
7//! memory, no locks, no channel wiring. Each actor processes messages sequentially from its
8//! own mailbox, making concurrent systems easier to reason about.
9//!
10//! ## Quick Start
11//!
12//! ```rust,no_run
13//! use maiko::*;
14//!
15//! #[derive(Event, Clone, Debug)]
16//! enum MyEvent {
17//!     Hello(String),
18//! }
19//!
20//! struct Greeter;
21//!
22//! impl Actor for Greeter {
23//!     type Event = MyEvent;
24//!
25//!     async fn handle_event(&mut self, envelope: &Envelope<Self::Event>) -> Result<()> {
26//!         if let MyEvent::Hello(name) = envelope.event() {
27//!             println!("Hello, {}!", name);
28//!         }
29//!         Ok(())
30//!     }
31//! }
32//!
33//! #[tokio::main]
34//! async fn main() -> Result<()> {
35//!     let mut sup = Supervisor::<MyEvent>::default();
36//!     sup.add_actor("greeter", |_ctx| Greeter, &[DefaultTopic])?;
37//!
38//!     sup.start().await?;
39//!     sup.send(MyEvent::Hello("World".into())).await?;
40//!     sup.stop().await
41//! }
42//! ```
43//!
44//! ## Core Types
45//!
46//! | Type | Description |
47//! |------|-------------|
48//! | [`Event`] | Marker trait for event types (use `#[derive(Event)]`) |
49//! | [`Actor`] | Trait for implementing actors |
50//! | [`Topic`] | Routes events to interested actors |
51//! | [`Supervisor`] | Manages actor lifecycles and runtime |
52//! | [`Context`] | Allows actors to send events and interact with runtime |
53//! | [`Envelope`] | Wraps events with metadata (sender, correlation ID) |
54//! | [`ActorId`] | Unique identifier for a registered actor |
55//!
56//! ## Topic-Based Routing
57//!
58//! Actors subscribe to topics, and events are automatically routed to all interested subscribers.
59//! Use [`DefaultTopic`] when you don't need routing, or implement [`Topic`] for custom filtering:
60//!
61//! ```rust,ignore
62//! #[derive(Debug, Hash, Eq, PartialEq, Clone)]
63//! enum MyTopic { Data, Control }
64//!
65//! impl Topic<MyEvent> for MyTopic {
66//!     fn from_event(event: &MyEvent) -> Self {
67//!         match event {
68//!             MyEvent::Data(_) => MyTopic::Data,
69//!             MyEvent::Control(_) => MyTopic::Control,
70//!         }
71//!     }
72//! }
73//!
74//! sup.add_actor("processor", |ctx| Processor::new(ctx), &[MyTopic::Data])?;
75//! ```
76//!
77//! ## Features
78//!
79//! - **`macros`** (default) - `#[derive(Event)]`, `#[derive(Label)]`, and `#[derive(SelfRouting)]` macros
80//! - **`monitoring`** - Event lifecycle hooks for debugging, metrics, and logging
81//! - **`test-harness`** - Test utilities for recording, spying, and asserting on event flow (enables `monitoring`)
82//! - **`serde`** - JSON serialization support (e.g. `Supervisor::to_json()`)
83//! - **`recorder`** - Built-in `Recorder` monitor for writing events to JSON Lines files (enables `monitoring` and `serde`)
84//!
85//! ## Examples
86//!
87//! See the [`examples/`](https://github.com/ddrcode/maiko/tree/main/maiko/examples) directory:
88//!
89//! - `pingpong.rs`  - Simple event exchange between actors
90//! - `guesser.rs`  - Multi-actor game with topics and timing
91//! - `arbitrage.rs`  - Test harness demonstration
92
93mod actor;
94mod actor_id;
95mod config;
96mod context;
97mod envelope;
98mod error;
99mod event;
100mod label;
101mod meta;
102mod step_action;
103mod subscribe;
104mod supervisor;
105mod topic;
106
107mod internal;
108
109#[cfg(feature = "test-harness")]
110#[cfg_attr(docsrs, doc(cfg(feature = "test-harness")))]
111pub mod testing;
112
113#[cfg(feature = "monitoring")]
114#[cfg_attr(docsrs, doc(cfg(feature = "monitoring")))]
115pub mod monitoring;
116
117#[cfg(feature = "monitoring")]
118#[cfg_attr(docsrs, doc(cfg(feature = "monitoring")))]
119pub mod monitors;
120
121pub use actor::Actor;
122pub use actor_id::ActorId;
123pub use config::Config;
124pub use context::Context;
125pub use envelope::Envelope;
126pub use error::Error;
127pub use event::Event;
128pub use label::Label;
129pub use meta::Meta;
130pub use step_action::StepAction;
131pub use subscribe::Subscribe;
132pub use supervisor::Supervisor;
133pub use topic::{DefaultTopic, Topic};
134
135#[cfg(feature = "macros")]
136#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
137pub use maiko_macros::{Event, Label, SelfRouting};
138
139pub type Result<T = ()> = std::result::Result<T, Error>;
140pub type EventId = u128;
maiko/lib.rs

maiko/
lib.rs
