ghost_actor

GhostActor makes it simple, ergonomic, and idiomatic to implement async / concurrent code using an Actor model.

GhostActor uses only safe code, and is futures executor agnostic--use tokio, futures, async-std, whatever you want. The following examples use tokio.

What does it do?

The GhostActor struct is a 'static + Send + Sync cheaply clone-able handle for managing rapid, efficient, sequential, mutable access to internal state data.

Using the raw type:

```rust // set our initial state let (a, driver) = GhostActor::new(42_u32);

// spawn the driver--using tokio here as an example tokio::task::spawn(driver);

// invoke some logic on the internal state (just reading here) let result: Result = a.invoke(|a| Ok(*a)).await;

// assert the result assert_eq!(42, result.unwrap()); ```

Best Practice: Internal state in a New Type:

GhostActor is easiest to work with when you have an internal state struct, wrapped in a new type of a GhostActor:

```rust struct InnerState { age: u32, name: String, }

[derive(Clone, PartialEq, Eq, Hash)]

pub struct Person(GhostActor);

impl Person { pub fn new(age: u32, name: String) -> Self { let (actor, driver) = GhostActor::new(InnerState { age, name }); tokio::task::spawn(driver); Self(actor) }

pub async fn birthday(&self) -> String {
    self.0.invoke(|inner| {
        inner.age += 1;
        let msg = format!(
            "Happy birthday {}, you are {} years old.",
            inner.name,
            inner.age,
        );
        <Result::<String, GhostError>>::Ok(msg)
    }).await.unwrap()
}

}

let bob = Person::new(42, "Bob".tostring()); asserteq!( "Happy birthday Bob, you are 43 years old.", &bob.birthday().await, ); ```

Using traits (and GhostFuture) to provide dynamic actor types:

```rust pub trait Fruit { // until async traits are available in rust, you can use GhostFuture fn eat(&self) -> GhostFuture;

// allows implementing clone on BoxFruit
fn box_clone(&self) -> BoxFruit;

}

pub type BoxFruit = Box;

impl Clone for BoxFruit { fn clone(&self) -> Self { self.box_clone() } }

[derive(Clone, PartialEq, Eq, Hash)]

pub struct Banana(GhostActor);

impl Banana { pub fn new() -> BoxFruit { let (actor, driver) = GhostActor::new(0); tokio::task::spawn(driver); Box::new(Self(actor)) } }

impl Fruit for Banana { fn eat(&self) -> GhostFuture { let fut = self.0.invoke(|count| { count += 1; >::Ok(count) });

    // 'resp()' is a helper function that builds a GhostFuture
    // from any other future that has a matching Output.
    resp(async move {
        Ok(format!("ate {} bananas", fut.await.unwrap()))
    })
}

fn box_clone(&self) -> BoxFruit {
    Box::new(self.clone())
}

}

// we could implement a similar 'Apple' struct // that could be interchanged here: let fruit: BoxFruit = Banana::new(); assert_eq!("ate 1 bananas", &fruit.eat().await.unwrap()); ```

Custom GhostActor error types:

The GhostActor::invoke() function takes a generic error type. The only requirement is that it must implement From<GhostError>:

```rust

[derive(Debug)]

struct MyError; impl std::error::Error for MyError {} impl std::fmt::Display for MyError { fn fmt(&self, f: &mut std::fmt::Formatter<'>) -> std::fmt::Result { write!(f, "{:?}", self) } } impl From for MyError { fn from(: GhostError) -> Self { Self } }

let (actor, driver) = GhostActor::new(42u32); tokio::task::spawn(driver); asserteq!(42, actor.invoke(|inner| { >::Ok(*inner) }).await.unwrap()); ```

Code Examples:

• Bounce: cargo run --example bounce

Contributing:

This repo uses cargo-task.

rust cargo install cargo-task cargo task