7 releases

0.2.3 Jun 19, 2024
0.2.2 May 14, 2018
0.1.2 May 8, 2018
0.1.0 Dec 29, 2017

#174 in Concurrency

MIT/Apache

18KB
280 lines

Build Status Build status Current Crates.io Version Document

may_actor

rust native actor library based on may

with this library

  • you don’t need to declare messages that passed into the actor
  • you don’t have to implement “actor” interface or trait for your actor.
  • the actors will automatically have M:N scheduling powered by may

Usage

extern crate may_actor;
use may_actor::Actor;

fn main() {
    struct HelloActor(u32);
    let a = Actor::new(HelloActor(0));

    a.call(|me| {
        me.0 = 10;
        println!("hello world");
    });
    // the with would wait previous messages process done
    a.with(|me| println!("actor value is {}", me.0));
}

for a detailed example, please see pi.rs

Features

  • send message via closure (Actor.call)

You can send messages to the actor with the call API. It accepts a closure that has the &mut T as parameter, so that you can change it’s internal state. The closure would be send to a queue inside the actor, and the actor would execute the closure asynchronously by a coroutine that associate with it . This API would not block user’s execution and would return immediately. if panic happens in the closure, it will be caught and ignored in actor's coroutine context.

  • synchronously run a closure within actor coroutine context (Actor.with)

You can also synchronously manipulate the actor's internal state by the with API. It accepts a closure that has the &mut T as parameter, so that you can view or modify actor's internal state. The closure would be executed by the associated coroutine if there are no other pending messages. And it will block until the closure returns the result to caller. If any panic happens in the closure, it will propagate to the caller's context

  • convert from raw instance reference to Actor (Actor.from)

You can transmute a &self type unsafely to it's handle type Actor<T>. This is convenient when need to get an actor handle in the implementation that need to pass as a function parameter.

However transmute from non actor context would trigger undefined behavior.

  • Allow panic inside a closure message, and this would not kill the actor, the actor will continue to process successive messages.

  • The actor can be cloned to get a new handle, this is just like how Arc<T> works, if all the actor handle got dropped, the associated coroutine will automatically exit.

Notice

  • Actor will catch panic and ignore the panic if any happened when processing a message, so there is no supervisor and restart policy right now. The actor only exit if all handles are dropped by user.
  • Don't call thread block APIs in passed in closures, call May version APIs instead.
  • This simple library doesn't support spawn actors across processes

License

may_actor is licensed under either of the following, at your option:

Dependencies

~3–28MB
~419K SLoC