> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# When to Use Stateful Actors

> Use a stateful actor when an entity has state that must be mutated coherently across many requests. Use a plain function for stateless work, and a database for cross-entity transactions or bulk queries.

Use a stateful actor when an **entity has state that must be mutated coherently across
many requests** — a cart, a chat room, a call leg's media state, a per-user rate
limiter, a job coordinator. One instance per name gives you serialized, durable, private
state for that entity without locks or a shared database.

## When Not to Reach for One

* **Stateless work** (routing, transforms, independent fan-out): use a plain function.
  An actor only adds a routing hop and a serialization point you don't need.
* **A global counter or singleton:** one name is one single-threaded instance is one
  throughput ceiling. Route everything through `idFromName("global")` and you've
  rebuilt the single-lock bottleneck. Shard across many names so load spreads across
  instances.
* **Large blobs or bulk scans:** the keyspace holds one entity's working set, not a
  warehouse. Use object storage or a database.
* **Cross-entity transactions or ad-hoc queries:** each instance is its own
  consistency domain. Within one actor, writes are serialized and `transaction()`
  gives you atomic multi-key updates — but there is no transaction across two actors,
  and there's no `JOIN` across them. If you need a
  transaction spanning many entities, or to query across them, that's what a database
  is for — keep it.

A single instance processes calls serially, so its ceiling is roughly
`1 / (method wall-time)` calls per second — the same ceiling one thread per account
gives you. Sharding by a well-chosen name is how you scale.

## Next Steps

* [How it works](/docs/edge-compute/stateful-actors/concepts/how-it-works) — the execution model and its limits
* [Addressing](/docs/edge-compute/stateful-actors/concepts/addressing) — choosing names that spread load
* [Shared actors](/docs/edge-compute/stateful-actors/shared-actors) — one actor, many functions