Crate maiko 

Maiko

A lightweight actor runtime for Tokio with topic-based pub/sub routing.

Maiko provides independent actors that communicate through asynchronous events -no shared memory, no locks, no channel wiring. Each actor processes messages sequentially from its own mailbox, making concurrent systems easier to reason about.

Quick Start

use maiko::*;

#[derive(Event, Clone, Debug)]
enum MyEvent {
    Hello(String),
}

struct Greeter;

impl Actor for Greeter {
    type Event = MyEvent;

    async fn handle_event(&mut self, envelope: &Envelope<Self::Event>) -> Result<()> {
        if let MyEvent::Hello(name) = envelope.event() {
            println!("Hello, {}!", name);
        }
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    let mut sup = Supervisor::<MyEvent>::default();
    sup.add_actor("greeter", |_ctx| Greeter, &[DefaultTopic])?;

    sup.start().await?;
    sup.send(MyEvent::Hello("World".into())).await?;
    sup.stop().await
}

Core Types

Type	Description
Event	Marker trait for event types (use #[derive(Event)])
Actor	Trait for implementing actors
Topic	Routes events to interested actors
Supervisor	Manages actor lifecycles and runtime
Context	Allows actors to send events and interact with runtime
Envelope	Wraps events with metadata (sender, correlation ID)
ActorId	Unique identifier for a registered actor

Topic-Based Routing

Actors subscribe to topics, and events are automatically routed to all interested subscribers. Use DefaultTopic for simple broadcasting, or implement Topic for custom routing:

#[derive(Debug, Hash, Eq, PartialEq, Clone)]
enum MyTopic { Data, Control }

impl Topic<MyEvent> for MyTopic {
    fn from_event(event: &MyEvent) -> Self {
        match event {
            MyEvent::Data(_) => MyTopic::Data,
            MyEvent::Control(_) => MyTopic::Control,
        }
    }
}

sup.add_actor("processor", |ctx| Processor::new(ctx), &[MyTopic::Data])?;

Features

• macros (default) - Enables #[derive(Event)] macro
• test-harness - Enables test utilities for asserting on event flow

Examples

See the examples/ directory:

• pingpong.rs - Simple event exchange between actors
• guesser.rs - Multi-actor game with topics and timing
• arbitrage.rs - Test harness demonstration

Structs

ActorId

Unique identifier for a registered actor.

Config

Runtime configuration for the supervisor and actors.

Context

Runtime-provided context for an actor to interact with the system.

DefaultTopic

Default topic for simple systems that don’t need topic-based routing.

Envelope

Event plus metadata used by the broker for routing and observability.

Meta

Metadata attached to every event envelope.

Subscribe

Specifies which topics an actor subscribes to.

Supervisor

Coordinates actors and the broker, and owns the top-level runtime.

Enums

Error

StepAction

Action returned by an actor step to influence scheduling.

Traits

Actor

Core trait implemented by user-defined actors.

Event

Marker trait for events processed by Maiko.

Topic

Maps events to routing topics.

Type Aliases

EventId

Result

Derive Macros

Event

SelfRouting

Derives Topic<Self> for Self enabling event-as-topic routing.