[][src]Crate ghost_actor

A simple, ergonomic, idiomatic, macro for generating the boilerplate to use rust futures tasks in a concurrent actor style.

What is GhostActor?

GhostActor boils down to a macro that helps you write all the boilerplate needed to treat a Future like an actor. When you "spawn" a GhostActor, you receive a handle called a "Sender", that allows you to make async requests and inline await async responses to/from you actor implementation's driver task.

The senders are cheaply clone-able allowing you to easily execute any number of parallel workflows with your task. When all senders are dropped, or if you explicitly call ghost_actor_shutdown(), the driver task (a.k.a. your Actor) will end.

Example

ghost_actor::ghost_actor! {
    // set the visibility of your actor - `Visibility()` for private.
    Visibility(pub),

    // name your actor - the main reference for interacting with your
    //                   actor will have the suffix "Sender" appended.
    //                   In this case: "MyActorSender".
    Name(MyActor),

    // any custom error set here must implement `From<GhostError>`
    Error(MyError),

    // specify your actor api
    Api {
        // Method names will be transformed into snake_case,
        // so, this method will be called "add_one".
        AddOne(
            // this string will be applied as docs to sender/handler
            "A test function, output adds 1 to input.",

            // the input type for your api
            u32,

            // the output type for your api
            u32,
        ),
    }
}

/// An example implementation of the example MyActor GhostActor.
struct MyActorImpl;

// The generics for a handler are:
// 1 - the "custom" type you'd like to allow users of your api to send in.
// 2 - the "internal" type you'd like your handlers to send in.
// It is highly recommended to use a `ghost_chan!` type for these.
// However, if you have no use for these capabilities, use `()`.
impl MyActorHandler<(), ()> for MyActorImpl {
    fn handle_add_one(
        &mut self,
        input: u32,
    ) -> MyActorHandlerResult<u32> {
        Ok(async move {
            Ok(input + 1)
        }.boxed().into())
    }
}

impl MyActorImpl {
    /// Rather than using ghost_actor_spawn directly, use this simple spawn.
    pub async fn spawn() -> MyActorSender {
        use futures::future::FutureExt;

        let (sender, driver) = MyActorSender::ghost_actor_spawn(Box::new(|_internal_sender| {
            async move {
                Ok(MyActorImpl)
            }.boxed().into()
        })).await.unwrap();

        tokio::task::spawn(driver);

        sender
    }
}

#[tokio::main(threaded_scheduler)]
async fn main() {
    let mut sender = MyActorImpl::spawn().await;

    assert_eq!(43, sender.add_one(42).await.unwrap());

    sender.ghost_actor_shutdown().await.unwrap();

    assert_eq!(
        "Err(GhostError(SendError(SendError { kind: Disconnected })))",
        &format!("{:?}", sender.add_one(42).await),
    );
}

Implementing a Handler

The ghost_actor! macro is going to generate a "[Name]Handler" trait. To provide an implementation for your ghost_actor! type, you need an item that implements this trait (see example above).

In addition to all the handle_* methods that are auto-generated per the Api section in the macro, there are also provided implementations for handle_ghost_actor_custom and handle_ghost_actor_internal.

Please see any of the unit tests (or run cargo doc on a module containing your ghost_actor! macro invocation) for examples on how to implement a handler.

Implementing a Spawn function

While you can absolutely require users of your api to call YourTypeSender::ghost_actor_spawn(...) and instantiate your handler type inside the callback, it might be polite to provide a function that requires a little less boilerplate.

See the example above, however, there may be no need to expose the implemented item type at all, you could, for example:

/// internal private type
struct MyActorImpl;

impl MyActorHandler<(), ()> for MyActorImpl {
    // ...
}

/// Rather than using ghost_actor_spawn directly, use this simple spawn.
/// This spawn makes an assumption that we are in a tokio runtime,
/// if we don't want to make that assumption, we can also return the
/// driver future here.
pub async fn spawn_my_actor() -> MyActorSender {
    use futures::future::FutureExt;

    let (sender, driver) = MyActorSender::ghost_actor_spawn(Box::new(|_internal_sender| {
        async move {
            Ok(MyActorImpl)
        }.boxed().into()
    })).await.unwrap();

    tokio::task::spawn(driver);

    sender
}

The ghost_chan! macro.

The ghost_chan! macro has an identical API to the ghost_actor! macro. And, in fact, the ghost_actor! macro invokes ghost_chan! to produce an internal enum for sending messages from your Sender struct.

When implementing a ghost actor Handler that will make use of Custom and/or Internal types, it is recommended to use a ghost_chan! enum as this type.

See the unit/integration tests for examples on making use of these.

Modules

dependencies

Re-exported dependencies to help with macro references.

example

Example usage for unit testing and showing documentation generation.

ghost_chan

The ghost_chan! macro generates an enum and helper types that make it easy to make inline async requests and await responses.

Macros

ghost_actor

Call ghost_actor! to generate the boilerplate for GhostActor implementations.

ghost_chan

The ghost_chan! macro generates an enum and helper types that make it easy to make inline async requests and await responses.

Enums

GhostError

Ghost error type.

Type Definitions

GhostActorDriver

This future represents a spawned GhostActor task, you must await or spawn this task into an executor for the actor to function.

GhostActorSpawn

This is the factory callback signature for spawning new actor tasks.

GhostResult

Ghost Result Type.