Crate aurum_actors[][src]

Expand description

Aurum implements a distributed actor model. Its purpose is to make distributed programming easy. Aurum provides support for clustering, CRDT sharing among cluster members and IoT device tracking. It has excellent type safety and full serde support.

Prerequisite Knowledge

We suggest having this knowledge before starting here:

Why Would You Want to Use Aurum?

Typed Actors

Actor references are typed, meaning they can only receive messages of a specific type. Untyped actor references can receive messages of any type. Typed references add safety by turning some runtime errors into compile time errors, and eliminate the need for catch-all match branches that handle invalid messages. They also make code easier to read. Type information gives extra hints of an actor’s role in the program. Actor references are statically typed. The type of messages they receive must be defined at compile time. Generics are used to communicate the types of messages. Most distributed actor model implementations use untyped actors.

Actor Interfaces

It is not unusual for someone to want to store actor references in a data structure (for instance, to keep track of subscribers to events). Collections in Rust must be homogeneous, but there may be many different kinds of actors who want to subscribe to the same events. You cannot keep actor references receiving different types in the same data structure, nor is creating a different structure for every possible type desirable, nor do we want to create separate actors that relay event messages to the real subscriber under its preferred type. Actor interfaces allow the programmer to define a subset of message types receivable by an actor, and create actor references which receive only that subset.

Actor interfaces are also useful if some of the messages an actor receives are serializable, and others are not. You can define a serializable subset, and create actor references that receive that subset. Aurum provides annotations on message types to create automatic translations between subtypes and root message types.

Forgeable References

Aurum was created to address fill niches in existing actor models like Akka. While Akka has support for both typed and untyped actors, typed actor references in Akka are not forgeable (i.e. they cannot be created independently). With Akka’s typed actors, you need a complex discovery protocol built underneath to acquire a reference to the actor for sending messages.

A single system may have many actors running on it, so these actors receive their messages on same network socket. Messages are then routed locally using a registry. Each actor is registered on their socket with a unique identifier. Our problem comes from Akka using strings for its actor identifiers. Strings do not contain any type information about the actor, so how do we know what type to give our reference we just forged? It’s not safe to just guess. Aurum fixes this problem by embedding type information within actor identifiers. Identifiers consist of both a string and a type id for discriminating between identifiers with the same string name. The type safety of forged references is enforced at compile time. None of this type safety comes at the cost of performance.

Modules and Features

Aurum is a heavily modularized piece of software. cluster is built on top of core with no internal access. If you plan on building a library on top of Aurum, cluster is a good reference.

  • cluster: Single data center clustering.
    • crdt: Intra-cluster CRDT sharing.
    • devices: External node management. Useful for IoT.
  • core: The basics. Start here if you’re new to Aurum and want to learn how to use it.
  • testkit: Tools for testing actors and injecting failures.


Aurum’s base functionality: spawning actors, binding sockets, forging actor references and sending messages.


Creates a UnifiedType and implements traits for it.

Derive Macros

Implements RootMessage and other traits for a root message type.