Coerce-rs coerce-rs

Coerce-rs is an asynchronous (async/await) Actor runtime and distributed system framework for Rust. It allows for extremely simple yet powerful actor-based distributed system development. With minimal code, you can build a highly scalable, fault-tolerant modern actor-driven application.

Features

Actors

Remoting

Distributed Sharding

Persistence

Distributed PubSub

HTTP API

How to build

Building Coerce is easy. All you need is the latest Rust stable or nightly installed, along with Cargo. ```shell

Clone the repository

git clone https://github.com/leonhartley/coerce-rs && cd coerce-rs

run Cargo build to build the entire workspace, including the examples and the tests

cargo build

Alternatively, if you'd like to build the library, dependencies and run the tests

cargo test ```

How to run the examples

Sharded Chat example

ActorSystem

Every actor belongs to an ActorSystem.

async/await Actors

An actor is just another word for a unit of computation. It can have mutable state, it can receive messages and perform actions. One caveat though.. It can only do one thing at a time. This can be useful because it can alleviate the need for thread synchronisation, usually achieved by locking (using Mutex, RwLock etc).

How is this achieved in Coerce?

Coerce uses Tokio's MPSC channels (tokio::sync::mpsc::channel), every actor created spawns a task listening to messages from a Receiver, handling and awaiting the result of the message. Every reference (ActorRef<A: Actor>) holds a Sender<M> where A: Handler<M>, which can be cloned.

Actors can be stopped and actor references can be retrieved by ID from anywhere in your application. IDs are String but if an ID isn't provided upon creation, a new Uuid will be generated. Anonymous actors are automatically dropped ( and Stopped) when all references are dropped. Tracked actors (using global fn new_actor) must be stopped.

Basic ActorSystem + EchoActor example

Example

```rust pub struct EchoActor {}

[async_trait]

impl Actor for EchoActor {}

pub struct EchoMessage(String);

impl Message for EchoMessage { type Result = String; }

[async_trait]

impl Handler for EchoActor { async fn handle( &mut self, message: EchoMessage, _ctx: &mut ActorContext, ) -> String { message.0.clone() } }

pub async fn run() { let mut actor = new_actor(EchoActor {}).await.unwrap();

let helloworld = "hello, world".tostring(); let result = actor.send(EchoMessage(hello_world.clone())).await;

asserteq!(result, Ok(helloworld)); } ```

Timer Example

```rust pub struct EchoActor {}

[async_trait]

impl Actor for EchoActor {}

pub struct EchoMessage(String);

impl Message for EchoMessage { type Result = String; }

pub struct PrintTimer(String);

impl TimerTick for PrintTimer {}

[async_trait]

impl Handler for EchoActor { async fn handle(&mut self, msg: PrintTimer, _ctx: &mut ActorContext) { println!("{}", msg.0); } }

pub async fn run() { let mut actor = newactor(EchoActor {}).await.unwrap(); let helloworld = "hello world!".to_string();

// print "hello world!" every 5 seconds let timer = Timer::start(actor.clone(), Duration::fromsecs(5), TimerTick(helloworld));

// timer is stopped when handle is out of scope or can be stopped manually by calling .stop() sleep(Duration::from_secs(20)).await; timer.stop(); } ```

RemoteActorSystem