Proto.Actor Framework
TL;DR: Just show me the code!
Project links
- Official site: proto.actor
- Source repositories: asynkron/protoactor-dotnet, asynkron/protoactor-go
- Example repositories: Proto.Actor .NET examples, Proto.Actor Go examples
Recommended learning path
- Start here → Hello World & Getting Started – Run your first actor and learn the essentials of the API surface.
- Explore core concepts – Understand why Proto.Actor exists and the vocabulary used throughout the docs.
- Build actors locally – Learn how actors are configured, spawned, and communicate inside a single node.
- Connect processes with Remote – Send messages across processes or machines with confidence.
- Scale out with Cluster – Introduce virtual actors, identity lookup, and production-grade hosting.
- Level up operations & patterns – Instrument, benchmark, and apply proven messaging patterns.
Language coverage quick reference
| Topic | .NET resources | Go resources |
|---|---|---|
| Getting started with grains / virtual actors | Getting Started (.NET) | Getting Started (Go) |
| Cluster code generation | Generating grains (.NET) | — |
| Cluster providers | Cluster providers (.NET) | — |
| Virtual actors deep dive | Working with a cluster (.NET) | Virtual Actors |
| Integration testing guidance | Integration Testing (.NET) | — |
| Dependency injection | Dependency Injection (.NET) | — |
| Futures and async responses | — | Futures (Go) |
Foundations
Introduction
Core concepts
- What is an Actor?
- What is a Message?
- Actor Communication
- Terminology, Concepts
- Supervision and Monitoring
- Fault Tolerance
- Actor lifecycle
- Location Transparency
- Message Delivery Reliability
- Message Patterns
- Actors vs Queues and Logs - Comparison and decision guide for messaging primitives
- Backpressure and Flow Control
- Consistency Models
- CAP Theorem
- Consensus and Leader Election
- Service Discovery
- Sharding and Data Partitioning
Build actor systems
Actor runtime building blocks
- Actor - What are actors?
- Props - How do I configure actors?
- Spawning Actors - How do I instantiate actors?
- PID - How do I communicate with actors?
- Context - What are actor and root contexts?
- ReenterAfter - How do I handle reentrancy in actors?
- Mailboxes - How does the actor process messages?
- Deadletter - What happens to lost messages?
- Router - How do I forward messages to pools or groups of workers?
- Eventstream - How are infrastructure events managed?
- Behaviors - How do I build state machines with actors?
- Middleware - How do I intercept or observe messages between actors?
- Receive Timeout - How do I trigger code when actors go idle?
- Dispatchers - How do I tweak how and where actors execute?
- Dealing with deadlocks
- Persistence of actor's state - How do I persist state for actors?
- Using 3rd party libraries - How do I persist state using external libraries?
- SimpleScheduler - How do I send messages on a timer?
- Built in messages
Distributed communication
- Remote - How do I communicate with actors on other nodes?
- Message Serialization
- Remote Spawning - How do I spawn actors on other nodes?
- gRPC Compression - How do I use gRPC compression for remote communication?
- Cluster of virtual actors / grains - How do I build clusters of grains / virtual actors?
- Working with a cluster (.NET)
- Generating grains (.NET)
- Cluster providers (.NET) - What different clustering options do I have?
- Identity lookup (.NET) - How to locate a virtual actor?
- Member strategies (.NET) - Which member will host the virtual actor?
- Gossip - How can I share state across cluster members?
- Blocklist - How do I handle blocked status of a member?
- Cluster Pub-Sub - Experimental - How to broadcast messages in the cluster?
- Virtual Actors - How do I create virtual actors and spawn them in the cluster?
- Integration Testing - How do I integration-test virtual actors?
Utility features
- AsyncSemaphore - How do I limit concurrency to a given resource?
- Batching Mailbox - How do I collect many events and process as single one unit?
- Throttle - How do I throttle method calls?
- Futures (Go) - How do I react to task completions?
- Dependency Injection (.NET) - How do I configure actors using Dependency Injection?
- Extensions and Context Decorator - How do I extend Proto.Actor with custom behaviors?
Advanced topics by persona
Operators and SREs
- Deploy to Kubernetes - Step-by-step deployment walkthrough.
- Observability Cookbook - Dashboards, tracing, and alerting recipes.
- Tracing
- Metrics
- Logging
- Health Checks
- Benchmarks
- Dotnetos performance review
Language-specific developers
- .NET
- Go
Useful Patterns
- Ask Pattern
- Idempotency in Messaging
- Message Throttling
- Work Pulling Pattern
- Limit Concurrency
- Scheduling Periodic Messages
- Envelope Pattern
- Local Affinity
- Placement Strategies
- Coordinated Persistence
- Batched Persistence
- Circuit Breaker Pattern
- Supervisor Strategy Recipes