Struct Task 

pub struct Task<Fut>(/* private fields */);

An actor that runs a future and is associated bidirectionally with its lifecycle: the actor dying stops the task, and the task dying kills the actor.

To support background tasks, Task holds its own ActorRef – it doesn’t die if you don’t hold a reference to it.

Kameo doesn’t natively provide functionality for this – ActorRef::attach_stream is the closest thing, but it doesn’t fit the mental model of a background task that doesn’t necessarily produce messages. So instead this is a thin wrapper around tokio::spawn, and the inner future kills the actor if the future completes.

Task implements Message<Infallible> so it can be addressed as a type-erased Recipient even though it doesn’t accept any messages.

If you need to be generic over the task future or would need to name the type of an anonymous future, it’s recommended to box the future and use ErasedTask as the task type.

Examples

Spawning a task that shares lifecycle with a parent:

struct Parent;

impl Actor for Parent {
    type Error = ();
    type Args = ();

    async fn on_start(_: (), slf: ActorRef<Self>) -> Result<Self, ()> {
        Task::spawn_link(&slf, async move {
            for i in 0.. {
                println!("{i}");
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        });

        // ... other self-init ...

        Ok(Self)
    }
}

let parent = Parent::spawn(());
tokio::time::sleep(Duration::from_millis(99)).await;
parent.kill();
// prints 0, 1, 2, 3, then the parent and task are killed

Trait Implementations

impl<Fut> Actor for Task<Fut>

where Fut: Future<Output = ()> + Send + 'static,

type Args = Fut

Arguments to initialize the actor.

type Error = Infallible

Actor error type.

async fn on_start( fut: Self::Args, slf: ActorRef<Self>, ) -> Result<Self, Self::Error>

Called when the actor starts, before it processes any messages.

async fn on_stop( &mut self, slf: WeakActorRef<Self>, reason: ActorStopReason, ) -> Result<(), Self::Error>

Called before the actor stops.

fn name() -> &'static str

The name of the actor, which can be useful for logging or debugging.

fn supervision_strategy() -> SupervisionStrategy

Defines the supervision strategy for this actor when acting as a supervisor.

fn on_message( &mut self, msg: Box<dyn DynMessage<Self>>, actor_ref: ActorRef<Self>, tx: Option<Sender<Result<Box<dyn Any + Send>, SendError<Box<dyn Any + Send>, Box<dyn Any + Send>>>>>, stop: &mut bool, ) -> impl Future<Output = Result<(), Box<dyn ReplyError>>> + Send

Called when the actor receives a message to be processed.

fn on_panic( &mut self, actor_ref: WeakActorRef<Self>, err: PanicError, ) -> impl Future<Output = Result<ControlFlow<ActorStopReason>, Self::Error>> + Send

Called when the actor encounters a panic or an error during “tell” message handling.

fn on_link_died( &mut self, actor_ref: WeakActorRef<Self>, id: ActorId, reason: ActorStopReason, ) -> impl Future<Output = Result<ControlFlow<ActorStopReason>, Self::Error>> + Send

Called when a linked actor dies.

fn next( &mut self, actor_ref: WeakActorRef<Self>, mailbox_rx: &mut MailboxReceiver<Self>, ) -> impl Future<Output = Result<Option<Signal<Self>>, Self::Error>> + Send

Awaits the next signal typically from the mailbox.

impl<Fut> Message<Infallible> for Task<Fut>

where Fut: Future<Output = ()> + Send + 'static,

type Reply = Infallible

The reply sent back to the message caller.

async fn handle( &mut self, _: Infallible, _: &mut Context<Self, Self::Reply>, ) -> Infallible

Handler for this message.

fn name() -> &'static str

The name of the message, which can be useful for logging or debugging.