Actors
An actor is a stateful object addressed by a key. Each key, such as a user id or a cart id, is its own instance with its own state, which the server stores. Workers run the actor's operations: an exclusive operation runs alone for its key, so it can read and write state without races.
Defining an Actor
1use orcher_sdk::prelude::*;23#[derive(Clone, Default, Serialize, Deserialize)]4pub struct Cart {5 pub items: Vec<String>,6}78#[actor(name = "cart")]9pub struct ShoppingCart;1011#[operations]12impl ShoppingCart {13 /// Runs alone for its key: no other operation on this cart overlaps it.14 #[operation(exclusive)]15 pub async fn add_item(ctx: ActorContext, item: String) -> Result<usize> {16 let state = ctx.state();17 let mut cart: Cart = state.get("cart").await?.unwrap_or_default();18 cart.items.push(item);19 state.set("cart", &cart).await?;20 Ok(cart.items.len())21 }2223 #[operation(exclusive)]24 pub async fn clear(ctx: ActorContext) -> Result<bool> {25 ctx.state().delete("cart").await26 }2728 /// Read-only: may run alongside other shared operations on this cart.29 #[operation(shared)]30 pub async fn view(ctx: SharedActorContext) -> Result<Cart> {31 Ok(ctx.state().get("cart").await?.unwrap_or_default())32 }33}#[actor(name = "...")]marks the type;namedefaults to the struct name. It is the actor type clients address.#[operations]turns each method marked#[operation(exclusive)]or#[operation(shared)]into an operation, and generates a typed client for them. Methods without#[operation]are kept as ordinary methods.- An operation is
async, takesActorContext(exclusive) orSharedActorContext(shared) first, any number of serializable arguments after it, and returnsorcher_sdk::Result<T>. - A worker built in the same binary registers the actor with the server when it is built, and runs its operations.
Operation Modes
| Mode | Context | Behavior |
|---|---|---|
#[operation(exclusive)] | ActorContext | Runs alone for its key: no other operation on the key overlaps it. May read and write state. |
#[operation(shared)] | SharedActorContext | Read-only. May run alongside other shared operations on the same key. The server rejects state writes from it. |
State
ctx.state() returns the instance's state store. Values are JSON, by string key:
| Method | Description |
|---|---|
get::<T>(key) | The value, or None |
set(key, &value) | Store a value (exclusive operations only) |
delete(key) | Remove a value; returns whether it existed |
exists(key) | Whether a value is stored |
list(prefix) | Keys, optionally with a prefix |
get_many::<T>(&keys) | Several values at once |
clear_all() | Remove every value of this instance |
ctx.key() and ctx.actor_name() identify the instance.
Calling Actors
From any process with a client:
1pub async fn shop(client: &Client) -> Result<()> {2 // A typed client for the cart with key "user-123". No request is made yet.3 let cart = client.actor::<ShoppingCart>("user-123");45 let count = cart.add_item("tea".to_string()).await?;6 println!("{count} items");78 let contents = cart.view().await?;9 println!("{:?}", contents.items);1011 cart.clear().await?;12 Ok(())13}client.actor::<ShoppingCart>(key) returns the generated client for that instance, with one async method per operation. It makes no request until you call one. Without the type, call an operation by name:
1pub async fn shop_by_name(client: &Client) -> Result<usize> {2 // The same call by actor and operation name, for code without the type.3 client4 .invoke_actor("cart", "user-456", "add_item", "coffee".to_string())5 .await6}client.send_actor(...) takes the same arguments and returns once the server has accepted the call, without waiting for the operation's result.
Workflows have no actor calls of their own. To use an actor from a workflow, call it from a task.
Testing
orcher_sdk::actor::testing::create_test_context builds a context with in-memory state, and #[operations] keeps each operation's body as <name>_impl, so an operation can be unit-tested without a server (Testing).