Actors
The fundamental building block of Cineyma applications.
What is an Actor?
An actor is an isolated unit of computation that:
- →Encapsulates state — Its internal state is completely private
- →Processes messages sequentially — One message at a time, no data races
- →Communicates via messages — No shared memory, only message passing
- →Can spawn child actors — Form supervision hierarchies
Defining an Actor
Any struct can become an actor by implementing the Actor trait:
Note: Actors must be Send + 'static to be spawned across async boundaries. This is enforced at compile time.
Actor Lifecycle
Every actor goes through a defined lifecycle:
Spawning Actors
Actors can be spawned from the actor system or from other actors:
Spawning Child Actors
Actors can spawn children that form a supervision hierarchy:
Important: When a parent actor stops, all its children are automatically stopped too. This enables clean shutdown of actor hierarchies.
Stopping Actors
Actors can be stopped in several ways:
Actor Identity
Every actor has a unique ActorId:
Best Practices
Keep actors focused
Each actor should have a single responsibility. Split complex logic across multiple actors.
Use supervision
Build fault-tolerant systems by organizing actors into supervision hierarchies.
Size mailboxes appropriately
Use larger mailboxes for high-throughput actors, smaller for low-traffic ones.
Don't share state directly
Never share mutable state between actors. Use messages instead.
Avoid blocking in handlers
Use AsyncHandler for I/O operations to avoid blocking other messages.