Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/govcraft/acton-reactive

The Acton Reactive Application Framework provides an efficient way to build fast, reactive Rust applications. Designed around an actor-based model, it simplifies concurrency and allows developers to focus on writing scalable, maintainable code. Acton gets its name from the fact that it "acts on" messages you define.
https://github.com/govcraft/acton-reactive

actor-framework actor-model concurrency concurrent-programming distributed-systems event-driven framework high-performance message-passing non-blocking rapid-development reactive reactive-programming rust rust-crate rust-lang rust-library systems-programming tokio type-safety

Last synced: 10 months ago
JSON representation

The Acton Reactive Application Framework provides an efficient way to build fast, reactive Rust applications. Designed around an actor-based model, it simplifies concurrency and allows developers to focus on writing scalable, maintainable code. Acton gets its name from the fact that it "acts on" messages you define.

Awesome Lists containing this project

README 

          
# Acton Reactive: Build Fast, Concurrent Rust Apps Easily



Welcome to Acton Reactive! This framework helps you build fast, concurrent Rust applications without getting tangled in complex threading or locking code.



Think of your application's logic broken down into independent workers called **Agents**. Each agent manages its own state and communicates with others by sending **Messages**. Acton Reactive handles the tricky parts of making these agents run concurrently and talk to each other efficiently, letting you focus on your application's features. It's built on top of [Tokio](https://tokio.rs/), Rust's powerful asynchronous runtime.



## Why Acton Reactive?



*   **Simplified Concurrency:** Forget manual thread management and complex locking. Agents run independently, managing their own data. Acton ensures messages are processed safely, making concurrent programming more approachable.

*   **Asynchronous & Performant:** Leverages Rust's `async/await` and Tokio for high-performance, non-blocking operations. Your application stays responsive, even under load.

*   **Organized & Maintainable Code:** Encourages breaking down complex problems into smaller, self-contained agents. This makes your codebase easier to understand, test, and maintain.

*   **Type-Safe Communication:** Define clear message types. Rust's compiler helps ensure you're sending and receiving the right kinds of messages, catching errors before runtime.

*   **Built-in Observability:** Integrates with the `tracing` crate, providing insights into your application's behavior for easier debugging and performance monitoring.



## Core Concepts Explained Simply



Before diving into code, let's understand the main building blocks:



1.  **Agent:** The fundamental unit. It's a Rust struct (that implements `Default` and `Debug`) which holds some internal state (its `model`) and reacts to incoming messages. Think of it as an independent worker or service.

2.  **Message:** A simple Rust struct (that implements `Debug` and `Clone`) used for communication. Agents send messages to other agents (or themselves) to trigger actions or share information. The `#[acton_message]` macro helps derive the required traits easily.

3.  **Handler (`act_on`):** A piece of code you define for an agent that specifies *how* it should react when it receives a particular type of message. Handlers can modify the agent's internal state (`model`) and send messages. They return an `AgentReply`.

4.  **Handle (`AgentHandle`):** An inexpensive, cloneable reference to an agent. You use an agent's handle to send messages *to* it from outside, or from other agents.

5.  **Runtime (`ActonApp` / `AgentRuntime`):** The Acton system environment. You launch it using `ActonApp::launch()`. It manages the agents, their communication channels, and the central message broker.



## Getting Started: A Basic Example



Let's build a simple counter agent.



1.  **Add Acton Reactive to your `Cargo.toml`:**



    ```toml

    [dependencies]

    acton_reactive = { version = "1.1.0-beta.1" } # Use the latest version

    tokio = { version = "1", features = ["full"] } # Acton requires a Tokio runtime

    anyhow = "1" # Useful for error handling in main

    ```



2.  **Write the code (`src/main.rs`):**



    ```rust

    use acton_reactive::prelude::*;

    use std::time::Duration;

    use anyhow::Result;



    // 1. Define the Agent's state (must be Default + Debug)

    #[derive(Debug, Default)]

    struct CounterAgent {

        count: i32,

    }



    // 2. Define Messages (must be Debug + Clone)

    // Use the macro for convenience!

    #[acton_message]

    struct IncrementMsg;



    #[acton_message]

    struct PrintMsg;



    // 3. The main async function (requires a Tokio runtime)

    #[tokio::main]

    async fn main() -> Result<()> {

        println!("Launching Acton application...");



        // 4. Launch the Acton Runtime

        let mut app = ActonApp::launch();



        // 5. Create an Agent Builder

        // This prepares an agent but doesn't start its processing loop yet.

        let mut counter_builder = app.new_agent::().await;

        println!("Created agent builder for: {}", counter_builder.id());



        // 6. Define Message Handlers using `act_on`

        counter_builder

            .act_on::(|agent, _context| {

                // This code runs when the agent receives an IncrementMsg.

                // We can safely mutate the agent's internal state (`model`).

                agent.model.count += 1;

                println!("Agent {}: Incremented count to {}", agent.id(), agent.model.count);

                // No async work needed here, return immediately.

                AgentReply::immediate()

            })

            .act_on::(|agent, _context| {

                // This code runs when the agent receives a PrintMsg.

                println!("Agent {}: Current count is {}", agent.id(), agent.model.count);

                // We can also perform async operations within a handler.

                AgentReply::from_async(async move {

                    // Example: Simulate some async work

                    tokio::time::sleep(Duration::from_millis(50)).await;

                    println!("Agent {}: Finished async work in PrintMsg handler.", agent.id());

                    // No need to explicitly send anything back here for this example.

                })

            })

            // Optional: Define lifecycle hooks

            .after_stop(|agent| {

                 println!("Agent {}: Final count is {}. Stopping.", agent.id(), agent.model.count);

                 AgentReply::immediate()

            });



        // 7. Start the Agent

        // This spawns the agent's task and returns a handle for sending messages.

        let counter_handle = counter_builder.start().await;

        println!("Started agent: {}", counter_handle.id());



        // 8. Send Messages using the Handle

        println!("Sending IncrementMsg...");

        counter_handle.send(IncrementMsg).await;



        println!("Sending PrintMsg...");

        counter_handle.send(PrintMsg).await;



        println!("Sending another IncrementMsg...");

        counter_handle.send(IncrementMsg).await;



        // Give the agent a moment to process the last message and its async handler

        tokio::time::sleep(Duration::from_millis(100)).await;



        // 9. Shut down the application gracefully

        // This stops all agents and waits for them to finish.

        println!("Shutting down application...");

        app.shutdown_all().await?;

        println!("Application shut down.");



        Ok(())

    }

    ```



3.  **Run it:** `cargo run`



You should see output showing the agent being created, handling messages, incrementing its count, and finally stopping.



## Common Patterns



While the example above covers the basics, Acton Reactive supports more patterns:



*   **Replying to Messages:** Inside a handler, use `context.reply_envelope()` to get an envelope addressed back to the original sender, then use `.send(YourReplyMessage).await`.

*   **Sending to Specific Agents:** If an agent has the `AgentHandle` of another agent, it can create a new envelope using `context.new_envelope(&target_handle.reply_address())` and then `.send(YourMessage).await`.

*   **Asynchronous Operations:** As shown in the `PrintMsg` handler, use `AgentReply::from_async(async move { ... })` to perform non-blocking tasks (like I/O) within your handlers.

*   **Lifecycle Hooks:** Use `.before_start()`, `.after_start()`, `.before_stop()`, and `.after_stop()` on the agent builder to run code during agent initialization or shutdown.

*   **Publish/Subscribe (Broadcasting):** Agents can subscribe to specific message types using `agent_handle.subscribe::().await`. Anyone (often the central `AgentBroker` obtained via `app.broker()` or `agent.broker()`) can then `broadcast(MyMessageType)` to notify all subscribers. This is great for system-wide events.

*   **Supervision (Parent/Child Agents):** Agents can create and manage child agents using `agent_handle.supervise(child_builder).await`. Stopping the parent will automatically stop its children.



## Explore More Examples



For more detailed examples demonstrating patterns like broadcasting, replies, and agent lifecycles, check out the `acton-reactive/examples/` directory in this repository.



## Contributing



Contributions are welcome! Feel free to submit issues, fork the repository, and send pull requests. Let's make Acton Reactive even better together!



## License



This project is licensed under either of:



*   Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)

*   MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)



at your option.