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.
Crate | Purpose | Latest Version |
---|---|---|
coerce | The main Coerce runtime and framework | |
coerce-redis | Actor persistence provider for Redis. Enables event source and snapshots to be read and written from Redis. | |
coerce-macros | Useful macros allowing for quick implementations of snapshots, JSON-serialisable remote messages and more. | |
coerce-k8s | Kubernetes discovery provider, automatically discover cluster peers hosted in Kubernetes, based on a configurable pod-selection label |
First step to using Coerce in your project is to add the coerce crate dependency, this can be done by adding the following to your Cargo.toml:
[dependencies]
coerce = { version = "0.8", features = ["full"] }
tracing/valuable
Coerce provides support for tracing/valuable
, which can be used for enriching logs with information on the actor context. This is currently an unstable feature, which can be enabled by adding the coerce/tracing-unstable
feature and the following section to your .cargo/config.toml
file:
[build]
rustflags = ["--cfg", "tracing_unstable"]
Note: if your project already depends on tracing
crate, you'll need to enable the valuable
feature too!
ActorRef<A>
types (ActorRef may comprise of a LocalActorRef<A>
or a RemoteActorRef<A>
)Building Coerce is easy. All you need is the latest Rust stable or nightly installed, along with Cargo.
# 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 --all-features
Every actor belongs to an ActorSystem.
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).
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.