Module heph::actor_ref[−][src]

Expand description

Module containing actor references.

An actor reference is a generic reference to an actor that can run on the same thread, another thread on the same node or even running remotely.

Sending messages

The primary function of actor references is sending messages. This can be done by using the send or try_send methods. These methods don’t block, even the remote actor reference, but the methods don’t provided a lot of guarantees. It doesn’t even guarantee the order in which the messages arrive. What send does is asynchronously add the message to the queue of messages for the actor.

In case of thread-local actor reference this can be done directly. But for thread-safe actor references the message must first be send across thread bounds before being added to the actor’s message queue. Remote actor references even need to send this message across a network, a lot can go wrong here.

If guarantees are needed that a message is received or processed the receiving actor should send back an acknowledgment that the message is received and/or processed correctly.

This example shows a simple actor that prints all the messages it receives.

#![feature(never_type)]

use heph::actor;
use heph::rt::{self, Runtime, ThreadLocal};
use heph::spawn::ActorOptions;
use heph::supervisor::NoSupervisor;

fn main() -> Result<(), rt::Error> {
    let mut runtime = Runtime::new()?;
    runtime.run_on_workers(|mut runtime_ref| -> Result<(), !> {
        // Spawn the actor.
        let new_actor = actor as fn(_) -> _;
        let actor_ref = runtime_ref.spawn_local(NoSupervisor, new_actor, (), ActorOptions::default());

        // Now we can use the actor reference to send the actor a message.
        actor_ref.try_send("Hello world".to_owned()).unwrap();

        Ok(())
    })?;
    runtime.start()
}

/// Our actor.
async fn actor(mut ctx: actor::Context<String, ThreadLocal>) {
    if let Ok(msg) = ctx.receive_next().await {
        println!("got message: {}", msg);
    }
}

All actor references can be cloned, which is the easiest way to share them.

The example below shows how an actor reference is cloned to send a message to the same actor.

#![feature(never_type)]

use heph::actor;
use heph::rt::{self, Runtime, ThreadLocal};
use heph::spawn::ActorOptions;
use heph::supervisor::NoSupervisor;

fn main() -> Result<(), rt::Error> {
    let mut runtime = Runtime::new()?;
    runtime.run_on_workers(|mut runtime_ref| -> Result<(), !> {
        let new_actor = actor as fn(_) -> _;
        let actor_ref = runtime_ref.spawn_local(NoSupervisor, new_actor, (), ActorOptions::default());

        // To create another actor reference we can simply clone the
        // first one.
        let second_actor_ref = actor_ref.clone();

        // Now we can use both references to send a message.
        actor_ref.try_send("Hello world".to_owned()).unwrap();
        second_actor_ref.try_send("Bye world".to_owned()).unwrap();

        Ok(())
    })?;
    runtime.start()
}

/// Our actor.
async fn actor(mut ctx: actor::Context<String, ThreadLocal>) {
    if let Ok(msg) = ctx.receive_next().await {
        println!("First message: {}", msg);
    }

    if let Ok(msg) = ctx.receive_next().await {
        println!("Second message: {}", msg);
    }
}