Examples

Learn from working code. Each example demonstrates specific patterns and concepts.

Basic Actor

Location: examples/basic/main.rs

Demonstrates fundamental actor concepts: state management, message handling, and request-reply patterns.

#[acton_actor]
struct BasicActorState {
    some_state: usize,
}

#[acton_message]
struct PingMsg;

#[acton_message]
struct PongMsg;

actor_builder
    .mutate_on::<PingMsg>(|actor, ctx| {
        actor.model.some_state += 1;
        let reply = ctx.reply_envelope();
        Reply::pending(async move {
            reply.send(PongMsg).await;
        })
    })
    .mutate_on::<PongMsg>(|actor, _| {
        actor.model.some_state += 1;
        Reply::ready()
    })
    .after_stop(|actor| {
        assert_eq!(actor.model.some_state, 2);
        Reply::ready()
    });

cargo run --example basic

Lifecycle Hooks

Location: examples/lifecycles/main.rs

Shows all four lifecycle hooks and their execution order.

actor
    .before_start(|_| {
        println!("Preparing...");
        Reply::ready()
    })
    .after_start(|_| {
        println!("Ready!");
        Reply::ready()
    })
    .before_stop(|_| {
        println!("Finishing up...");
        Reply::ready()
    })
    .after_stop(|actor| {
        println!("Final state: {:?}", actor.model);
        Reply::ready()
    });

Execution order:

cargo run --example lifecycles

Broadcast Messaging

Location: examples/broadcast/main.rs

Demonstrates pub/sub messaging using the broker.

let broker = runtime.broker();

// Subscribe before starting
data_collector.handle().subscribe::<NewData>().await;
aggregator.handle().subscribe::<NewData>().await;
printer.handle().subscribe::<StatusUpdate>().await;

// Broadcast - all subscribed actors receive
broker.broadcast(NewData(5)).await;

cargo run --example broadcast

Configuration

Location: examples/configuration/main.rs

Shows how to load and use configuration files from XDG locations.

cargo run --example configuration

See Configuration for the full configuration guide.

Fruit Market

Location: examples/fruit_market/

A complete multi-actor application showing real-world patterns.

Components:

• Cart Actor: Manages shopping cart items
• Register Actor: Handles checkout
• Price Service: Provides price lookups
• Printer Actor: Displays receipts

Patterns demonstrated:

• Multi-actor coordination
• Actor-to-actor messaging
• Complex state management
• Request-reply across actors

cargo run --example fruit_market

IPC Examples

These examples require the ipc feature. See IPC Setup for configuration details.

IPC Basic

Foundation example for IPC setup and type registration.

cargo run --example ipc_basic --features ipc

IPC Bidirectional

Request-response patterns over IPC with multiple services.

# Terminal 1
cargo run --example ipc_bidirectional_demo --bin server --features ipc

# Terminal 2
cargo run --example ipc_bidirectional_demo --bin client --features ipc

IPC Streaming

Multi-frame streaming responses (countdowns, pagination).

# Terminal 1
cargo run --example ipc_streaming --bin server --features ipc

# Terminal 2
cargo run --example ipc_streaming --bin client --features ipc

IPC Subscriptions

Push notifications via broker subscriptions.

# Terminal 1
cargo run --example ipc_subscriptions --bin server --features ipc

# Terminal 2
cargo run --example ipc_subscriptions --bin client --features ipc

IPC Client Libraries

Polyglot clients in Python and Node.js.

# Terminal 1
cargo run --example ipc_client_libraries --features ipc

# Terminal 2
cd examples/ipc_client_libraries/python && python client.py
# or
cd examples/ipc_client_libraries/node && node client.js

IPC Fruit Market

Location: examples/ipc_fruit_market/

A multi-process point-of-sale system demonstrating advanced IPC patterns.

Components:

• Server: Central coordinator with PriceService actor
• Keyboard Client: Raw input capture, fire-and-forget commands
• Display Client: Reactive terminal UI with cart state

Patterns demonstrated:

• Fire-and-forget commands
• Push subscriptions
• Broker broadcasting
• State synchronization across processes

# Using tmux launcher (recommended)
cd acton-reactive/examples/ipc_fruit_market
./start.sh

# Or manually in 3 terminals:
cargo run --example ipc_fruit_market_server --features ipc
cargo run --example ipc_fruit_market_display --features ipc
cargo run --example ipc_fruit_market_keyboard --features ipc

IPC Multi-Service

Location: examples/ipc_multi_service/

Multiple actors via IPC, each providing a different service, with a real-time dashboard.

Services:

Features:

• IPC routing to services by logical name
• Real-time terminal dashboard
• Listener statistics monitoring
• Heartbeat/ping for connection health

# Terminal 1 - Server with dashboard
cargo run --example ipc_multi_service_server --features ipc

# Terminal 2 - Client
cargo run --example ipc_multi_service_client --features ipc

RGB Keyboard

Location: examples/rgb_keyboard/

Advanced IPC example with multiple patterns working together for a colorful keyboard visualization.

Components (6 processes):

• Server: Central hub correlating RGB responses
• R/G/B Clients: Subscribe to requests, generate random color values
• Input Client: Captures keystrokes
• Output Client: Displays characters with true RGB colors

Patterns demonstrated:

• Fire-and-forget (input → server)
• Broadcast/subscription (server → color clients)
• Request-response with correlation IDs
• Push notifications (server → output)

# Using tmux launcher (recommended)
cd acton-reactive/examples/rgb_keyboard
./start.sh

# Or manually in 6 terminals (see README)

Quick Reference

Running Examples

# List all examples
cargo run --example

# Run core examples
cargo run --example basic
cargo run --example lifecycles
cargo run --example broadcast
cargo run --example fruit_market

# IPC examples need the feature flag
cargo run --example ipc_basic --features ipc