Reference

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

1
use orcher_sdk::prelude::*;
2
3
#[derive(Clone, Default, Serialize, Deserialize)]
4
pub struct Cart {
5
pub items: Vec<String>,
6
}
7
8
#[actor(name = "cart")]
9
pub struct ShoppingCart;
10
11
#[operations]
12
impl 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
}
22
23
#[operation(exclusive)]
24
pub async fn clear(ctx: ActorContext) -> Result<bool> {
25
ctx.state().delete("cart").await
26
}
27
28
/// 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; name defaults 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, takes ActorContext (exclusive) or SharedActorContext (shared) first, any number of serializable arguments after it, and returns orcher_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

ModeContextBehavior
#[operation(exclusive)]ActorContextRuns alone for its key: no other operation on the key overlaps it. May read and write state.
#[operation(shared)]SharedActorContextRead-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:

MethodDescription
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:

1
pub 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");
4
5
let count = cart.add_item("tea".to_string()).await?;
6
println!("{count} items");
7
8
let contents = cart.view().await?;
9
println!("{:?}", contents.items);
10
11
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:

1
pub async fn shop_by_name(client: &Client) -> Result<usize> {
2
// The same call by actor and operation name, for code without the type.
3
client
4
.invoke_actor("cart", "user-456", "add_item", "coffee".to_string())
5
.await
6
}

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).


Next Steps

  • Client: connecting to the server
  • Worker: actor pollers and concurrency
  • Testing: testing actor operations