How slawlor/ractor works
Project type and purpose
• ractor is a pure-Rust actor framework library with an optional cluster extension (ractor_cluster).
• It provides Erlang-style gen_server semantics, actor supervision, timers, RPC, and named process registries.
• ractor_cluster adds networking: TCP listeners, node authentication, remote actors, and inter-node messaging via Protobuf protocols.
File structure
• Top-level crates:
– ractor: core actor framework
– ractor_cluster: distributed cluster support
– ractor_cluster_derive: procedural macros for message serialization
– ractor_cluster_integration_tests: end-to-end cluster tests in Docker
– ractor_example_entry_proc, ractor_playground: example consumers
– xtask: custom build/testing tasks
• Key directories in ractor:
– src/actor – actor lifecycle, ID, properties, supervisor logic
– src/concurrency – runtime adapters (tokio, async-std, WASM)
– src/factory – worker pools, routing, rate limiting
– src/registry – PID registry
– src/rpc – RPC primitives
– src/serialization – message serialization
– src/time – timer utilities
• In ractor_cluster:
– src/node – NodeServer, NodeSession, authentication
– src/net – TCP listener/session
– src/remote_actor – untyped serialized actor proxies
– protocol/*.proto – Protobuf definitions for control, meta, auth
README for additional insights
• Confirms core modules, feature flags (cluster, async-std, monitors, tracing)
• Describes actor model (signals, stop, supervision events, messages)
• Describes NodeServer responsibilities and NodeSession internals
Main components
a. Core Actor Runtime
– Actor API layer (Actor trait, Message trait)
– Supervisor subsystem (supervision trees, lifecycle events)
– Concurrency adapters (Tokio / Async-std / WASM)
– Message queue & dispatch engine
– Timers and scheduling
– Registry & process groups
– RPC handler
b. Cluster Extension
– NodeServer (TCP listener, cluster manager)
– NodeSession (network I/O, authentication, session actor)
– RemoteActor proxies (serialization boundary)
– Protobuf protocol modules
c. Application Layer
– User-defined actors (examples, playground, entry_proc)
– Procedural macros for deriving Message traits
– Integration test harness (Dockerized CA, env files)
Relationships and interactions
• Application code → uses Actor::spawn → communicates via Actor API → Core runtime
• Runtime → forks tasks onto underlying async runtime (Tokio/Async-std)
• Actors send messages to each other via the central message queue
• Supervision events flow from child actors up to supervisors
• Timers trigger actor messages
• Registry resolves actor names to ActorRefs
• RPC calls packaged and dispatched within the core RPC module
• When cluster feature is enabled:
– NodeServer spawns NodeSession per peer → manages TCP streams
– NodeSession serializes Actor messages (via prost using protocol/*.proto) → sends over TCP
– Incoming messages → NodeSession → deserializes → injects into local ActorRef as RemoteActor
• Integration tests use Docker Compose, CA certificates, and env files to simulate multi-node clusters
Architectural patterns and design principles
• Actor model with non-blocking, single-thread-per-actor semantics
• Supervision trees for fault tolerance (Erlang pattern)
• Adapter pattern for runtime binding (Tokio vs Async-std)
• Factory pattern for worker pools and routing
• Modular layering: Core runtime, cluster extension, user applications
Be detailed and capture essential elements
• Break the core into logical subcomponents (actor, concurrency, registry, RPC, factory, time)
• Async runtime adapters as a separate sub-layer
• In cluster, show the Protobuf files feeding into the serialization engine
• Avoid over-splitting: group similar modules but separate runtime, core logic, and network