Crate heph

Heph, derived from Hephaestus, is the Greek god of blacksmiths, metalworking, carpenters, craftsmen, artisans, sculptors, metallurgy, fire, and volcanoes. Well this crate has very little to do with Greek gods, but I needed a name.

About

Heph is an actor framework based on asynchronous functions. Such an asynchronous function looks like this:

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

Heph uses an event-driven, non-blocking I/O, share nothing design. But what do all those buzzwords actually mean?

• Event-driven: Heph does nothing by itself, it must first get an event before it starts doing anything. For example when using a TcpListener it waits on a notification from the OS saying the TcpListener is ready before trying to accept connections.
• Non-blocking I/O: normal I/O operations need to wait (block) until the operation can complete. Using non-blocking, or asynchronous, I/O means that rather then waiting for the operation to complete we’ll do some other, more useful, work and try the operation later.
• Share nothing: a lot of application share data across multiple threads. To do this safely we need to protect it from data races, via a Mutex or by using atomic operations. Heph is designed to not share any data. Each actor is responsible for its own memory and cannot access memory owned by other actors. Instead communication is done via sending messages, see the actor model.

Getting started

There are two ways to get starting with Heph. If you like to see examples, take a look at the examples in the examples directory of the source code. If you like to learn more about some of the core concepts of Heph start with the Quick Start guide.

Features

This crate has one optional: test. The test feature will enable the test module which adds testing facilities.

Re-exports

pub use actor::Actor;

pub use actor::NewActor;

pub use actor_ref::ActorRef;

pub use supervisor::Supervisor;

pub use supervisor::SupervisorStrategy;

Modules

actor

The module with the actor trait and related definitions.

actor_ref

Module containing actor references.

messages

Standardised messages.

quick_start

Quick Start Guide

supervisor

The module with the supervisor and related types.

Macros

from_message

Macro to implement From for an enum message type.

restart_supervisor

Macro to create a supervisor that logs the error and restarts the actor.