Module heph::actor

Expand description

The module with the actor trait and related definitions.

Actors come in three different kinds:

Asynchronous thread-local actors,
Asynchronous thread-safe actors, and
Synchronous actors.

Both asynchronous actors must implement the Actor trait, which defines how an actor is run. The NewActor defines how an actor is created and is used in staring, or spawning, new actors. The easiest way to implement these traits is to use asynchronous functions, see the example below.

The following sections describe each kind of actor, including up- and downsides of each kind.

Asynchronous thread-local actors

Asynchronous thread-local actors, often referred to as just thread-local actors, are actors that will remain on the thread on which they are started. They can be started, or spawned, using RuntimeRef::try_spawn_local, or any type that implements the Spawn trait using the ThreadLocal context. These should be the most used as they are the cheapest to run.

The upside of running a thread-local actor is that it doesn’t have to be Send or Sync, allowing it to use cheaper types that don’t require synchronisation. The downside is that if a single actor blocks it will block all actors on the thread. Something that some frameworks work around with actor/tasks that transparently move between threads and hide blocking/bad actors, Heph does not (for thread-local actor).

Asynchronous thread-safe actors

Asynchronous thread-safe actors, or just thread-safe actor, are actors that can be run on any of the worker threads and transparently move between them. They can be spawned using RuntimeRef::try_spawn, or any type that implements the Spawn trait using the ThreadSafe context. Because these actor move between threads they are required to be Send and Sync.

An upside to using thread-safe actors is that a bad actor (that blocks) only blocks a single worker thread at a time, allowing the other worker threads to run the other thread-safe actors (but not the thread-local actors!). A downside is that these actors are more expansive to run than thread-local actors.

Synchronous actors

The previous two asynchronous actors, thread-local and thread-safe actors, are not allowed to block the thread they run on, as that would block all other actors on that thread as well. However sometimes blocking operations is exactly what we need to do, for that purpose Heph has synchronous actors.

Synchronous actors run own there own thread and can use blocking operations, such as blocking I/O. Instead of an actor::Context they use a SyncContext, which provides a similar API to actor::Context, but uses blocking operations. To support blocking operations each synchronous actor requires their own thread to run on, this makes sync actors the most expansive to run (by an order of a magnitude).

The SyncActor trait defines how an actor is run and is the synchronous equivalent of NewActor and Actor within a single trait.

Examples

Using an asynchronous function to implement the NewActor and Actor traits.

use heph::actor::{self, NewActor};
use heph_rt::ThreadLocal;

async fn actor(ctx: actor::Context<(), ThreadLocal>) {
    println!("Actor is running!");
}

// Unfortunately `actor` doesn't yet implement `NewActor`, it first needs
// to be cast into a function pointer, which does implement `NewActor`.
use_actor(actor as fn(_) -> _);

fn use_actor<NA>(new_actor: NA) where NA: NewActor {
    // Do stuff with the actor ...
}

Spawning and running a synchronous actor using a regular function.

use heph::actor::SyncContext;
use heph::supervisor::NoSupervisor;
use heph_rt::spawn::SyncActorOptions;
use heph_rt::{self as rt, Runtime};

fn main() -> Result<(), rt::Error> {
    // Spawning synchronous actor works slightly different from spawning
    // regular (asynchronous) actors. Mainly, synchronous actors need to be
    // spawned before the runtime is started.
    let mut runtime = Runtime::new()?;

    // Spawn a new synchronous actor, returning an actor reference to it.
    let actor = actor as fn(_, _);
    let options = SyncActorOptions::default();
    let actor_ref = runtime.spawn_sync_actor(NoSupervisor, actor, "Bye", options)?;

    // Just like with any actor reference we can send the actor a message.
    actor_ref.try_send("Hello world".to_string()).unwrap();

    // And now we start the runtime.
    runtime.start()
}

fn actor<RT>(mut ctx: SyncContext<String, RT>, exit_msg: &'static str) {
    if let Ok(msg) = ctx.receive_next() {
        println!("Got a message: {}", msg);
    } else {
        eprintln!("Receive no messages");
    }
    println!("{}", exit_msg);
}