Crate hannibal 

Motivation

In async Rust, you often find yourself spawning tasks and creating channels to communicate between them. This can become cumbersome in larger projects and complicated when supporting multiple message types. An Actor is a task that can receive and handle messages and store internal state.

Simple Example

You can send messages to an actor without expecting a response.

#[derive(Actor)]
struct Greeter(&'static str);

#[message]
struct Greet(&'static str);

impl Handler<Greet> for Greeter {
    async fn handle(&mut self, _ctx: &mut Context<Self>, msg: Greet) {
        println!(
            "[Actor {me}] Hello {you}, my name is {me}",
            me = self.0,
            you = msg.0,
        );
    }
}

let mut addr = Greeter("Caesar").spawn();

addr.send(Greet("Hannibal")).await.unwrap();

You can also call the actor and get a response.

#[derive(Actor)]
struct Calculator();

#[message(response = i32)]
struct Add(i32, i32);

impl Handler<Add> for Calculator {
    async fn handle(&mut self, _ctx: &mut Context<Self>, msg: Add) -> i32 {
        msg.0 + msg.1
    }
}

let mut addr = Calculator().spawn();

let addition = addr.call(Add(1, 2)).await;

println!("The Actor Calculated: {:?}", addition);

Runtime behavior

Actors can also be used to handle Streams by implementing StreamHandler, they can be configured to enforce timeouts and use bounded or unbounded channels under the hood. Take a look at hannibal::builder to see how to configure an actor’s runtime behavior and how to launch them on streams.

Modules

builder

Configure the runtime behavior of actor instances.

error

Error types for the actor system.

prelude

Re-exports the most commonly used traits and types.

runtime

Runtime utilities.

service

Provides the Service trait and implementations.

spawnable

Abstractions for spawning and managing actors in an asynchronous environment. Currently hannibal supports both tokio and smol async-global-executore.

Structs

Addr

A strong reference to an actor.

Broker

Enables global subscriptions and message distribution.

Caller

A strong reference to some actor that can receive a message M and respond.

Context

Available to the actor in every execution call.

OwningAddr

An even stronger reference to an actor.

Sender

A strong reference to some actor that can receive message M.

TaskHandle

Represents a handle to a task that can be used to abort the task.

WeakAddr

A weak reference to an actor.

WeakCaller

A weak reference to an actor that can receive a message M and respond.

WeakSender

A weak reference to an actor that can receive a message M.

Traits

Actor

An actor is an object that can receive messages.

Handler

An actor should implement this trait if it wants to handle messages.

Message

Anything that you want to send to an actor.

RestartableActor

A marker trait for actors that can be restarted.

Service

A service is an actor that does not need to be owned

StreamHandler

An actor should implement this trait if it wants to handle messages from a stream.

Functions

build

Start constructing an actor.

Type Aliases

DynResult

Convenience type alias for Box<dyn std::error::Error + Send + Sync>.

Attribute Macros

main

message