Trait xtra::Actor

pub trait Actor: 'static + Sized {
    fn started(&mut self, ctx: &mut Context<Self>) { ... }
    fn stopping(&mut self, ctx: &mut Context<Self>) -> KeepRunning { ... }
    fn stopped(&mut self, ctx: &mut Context<Self>) { ... }
    fn spawn(self) -> Address<Self>
    where
        Self: Send,
    { ... }
    fn create(self) -> (Address<Self>, ActorManager<Self>) { ... }
}

An actor which can handle Messages one at a time. Actors can only be communicated with by sending Messages through their Addresses. They can modify their private state, respond to messages, and spawn other actors. They can also stop themselves through their Context by calling Context::stop. This will result in any attempt to send messages to the actor in future failing.

Example

struct MyActor;

impl Actor for MyActor {
    fn started(&mut self, ctx: &mut Context<Self>) {
        println!("Started!");
    }

    fn stopping(&mut self, ctx: &mut Context<Self>) -> KeepRunning {
        println!("Decided not to keep running");
        KeepRunning::No
    }

    fn stopped(&mut self, ctx: &mut Context<Self>) {
        println!("Finally stopping.");
    }
}

struct Goodbye;

impl Message for Goodbye {
    type Result = ();
}

impl SyncHandler<Goodbye> for MyActor {
    fn handle(&mut self, _: Goodbye, ctx: &mut Context<Self>) {
        println!("Goodbye!");
        ctx.stop();
    }
}

// Will print "Started!", "Goodbye!", "Decided not to keep running", and then "Finally stopping."
#[smol_potat::main]
async fn main() {
    let addr = MyActor.spawn();
    addr.send(Goodbye).await;

    Timer::after(Duration::from_secs(1)).await; // Give it time to run
}

For longer examples, see the examples directory.

Provided methods

fn started(&mut self, ctx: &mut Context<Self>)

Called as soon as the actor has been started.

fn stopping(&mut self, ctx: &mut Context<Self>) -> KeepRunning

Called when the actor calls the Context::stop. This method can prevent the actor from stopping by returning KeepRunning::Yes.

Note: this method will only be called when Context::stop is called. Other, general destructor behaviour should be encapsulated in the Actor::stopped method.

Example

fn stopping(&mut self, ctx: &mut Context<Self>) -> KeepRunning {
    self.is_running.into() // bool can be converted to KeepRunning with Into
}

fn stopped(&mut self, ctx: &mut Context<Self>)

Called when the actor is in the process of stopping. This could be because KeepRunning::No was returned from the Actor::stopping method, or because there are no more strong addresses (Address, as opposed to WeakAddress. This should be used for any final cleanup before the actor is dropped.

fn spawn(self) -> Address<Self> where
    Self: Send, 

This is supported on feature="with-tokio-0_2" and feature="with-async_std-1" and feature="with-wasm_bindgen-0_2" and feature="with-smol-0_1" only.

Spawns the actor onto the global runtime executor (i.e, tokio or async_std's executors).

Example

struct MyActor;

impl Actor for MyActor {
    fn started(&mut self, ctx: &mut Context<Self>) {
        println!("Started!");
    }
}


#[smol_potat::main]
async fn main() {
    let addr: Address<MyActor> = MyActor.spawn(); // Will print "Started!"
    addr.do_send(Msg).unwrap();

    Timer::after(Duration::from_secs(1)).await; // Give it time to run
}

fn create(self) -> (Address<Self>, ActorManager<Self>)

Returns the actor's address and manager in a ready-to-start state. To spawn the actor, the ActorManager::manage method must be called and the future it returns spawned onto an executor.

Example

#[smol_potat::main]
async fn main() {
    let (addr, mgr) = MyActor.create();
    smol::Task::spawn(mgr.manage()).detach(); // Actually spawn the actor onto an executor

    Timer::after(Duration::from_secs(1)).await; // Give it time to run
}

Loading content...

Implementors

Loading content...