Guides

Using Actors


Invoking Actors

Actors are invoked by sending an operation request with the actor name, instance key, and operation name. Orcher routes the request to an available worker that handles that actor type.

1
// `client` is a connected Client instance
2
3
// Create a type-safe proxy for a specific actor instance
4
const cart = client.actorRef(ShoppingCart, 'user-123');
5
6
// Invoke operations — ctx parameter is stripped, you just pass the business args
7
const updatedCart = await cart.addItem({ name: 'Widget', price: 9.99, quantity: 1 });
8
const total = await cart.getTotal();

Registering Actors with a Worker

Actors are registered with the worker builder alongside workflows and tasks. The worker handles polling for operations and routing them to the correct actor handler.

1
import { WorkerBuilder } from '@orcher/sdk';
2
3
const worker = WorkerBuilder.new('cart-worker')
4
.serverUrl('http://localhost:50051')
5
.registerActor(ShoppingCart)
6
.build();
7
8
await worker.run();

Execution Model

Understanding how actors execute helps you write correct, performant operations.

Per-Key Queuing

Orcher maintains a per-key queue for each active actor instance. When an operation arrives for ShoppingCart["user-123"], it's placed in the queue for that specific key. The router dequeues operations one at a time (for exclusive) or in batches (for shared), ensuring the concurrency rules described above. An exclusive operation acts as a barrier between shared batches: the running batch drains, the exclusive runs alone, and shared operations that arrived in the meantime run after it.

If a worker picks up an operation and never reports back — for example, it crashes mid-execution — the operation times out and fails rather than blocking the key indefinitely; the caller receives a timeout error and the queue moves on.

Worker Polling

Workers poll the server for actor operations, similar to how they poll for workflow tasks. The server returns the next operation from the global work queue, and the worker executes it using the locally registered actor handler. Results are reported back to the server.

State Persistence

All state operations (get, set, delete) are RPC calls to the server, which persists state in PostgreSQL. This means:

  • Actors are transient — the worker process can restart and actors automatically resume from server-side state
  • State survives crashes — there's no in-memory state to lose
  • Multiple workers can handle the same actor type — the server routes operations to any available worker

Optimistic Locking

State writes support version-based optimistic locking via expected_version. If two operations race on the same state key, the second write fails with a version conflict, allowing the caller to retry. This is handled automatically for exclusive operations (since they're serialized), but is available as an extra safety layer for advanced use cases.


Best Practices

  1. Keep operations short. Each operation holds the per-key lock (for exclusive mode). Long-running operations block all other mutations for that key. If you need to do expensive work, offload it to a task or workflow and return quickly.

  2. Use shared mode for reads. Marking read-only operations as shared allows them to run concurrently, significantly improving read throughput for popular actor instances. Read-only is enforced: a shared operation that attempts a state write is rejected by the engine — keep every write in an exclusive operation.

  3. Scope state keys carefully. Use prefixed keys (item:widget, item:gadget) rather than storing everything in a single large object. This makes partial reads and updates more efficient.

  4. Don't store instance fields. Actor instances are transient. All important data must go through ctx.state. If a worker restarts, the actor is recreated from scratch with no instance memory.

  5. Prefer actors over workflows for entity state. If your use case is "manage the state of X" (a cart, a counter, a session), actors are a better fit than workflows. Workflows are better for "execute this sequence of steps."


Next Steps