Struct BackgroundHandle 

pub struct BackgroundHandle { /* private fields */ }

A cloneable capability handed to background-task subscribers so they can request cancellation of a single background task without tearing down the whole request.

The handle wraps a per-task CancellationToken (a child of the task context’s token). Calling stop cancels only that task: the producer’s background loop observes the cancellation and terminates the task, while sibling tasks and the enclosing request keep running. Request-level cancellation still cascades down, because the per-task token is a child of the request token.

The handle also carries a creation timestamp (for observing run time) and an optional, type-erased application payload attached with with_data. The payload is shared by Arc across every clone (the subscriber’s copy and the one kept in BackgroundTaskControls), so a subscriber can keep per-task bookkeeping on the handle itself instead of maintaining a parallel map. Use interior mutability (e.g. Mutex) inside the payload when it must change over the task’s lifetime.

Implementations

impl BackgroundHandle

pub fn new(task_id: impl Into<String>, token: CancellationToken) -> Self

Wraps a per-task cancellation token under its task ID. The creation timestamp is stamped now and no payload is attached.

pub fn with_data<T: Any + Send + Sync>(self, data: T) -> Self

Attaches an application-defined payload, wrapping it in an Arc so every clone of the handle observes the same value.

pub fn with_shared_data<T: Any + Send + Sync>(self, data: Arc<T>) -> Self

Attaches an already-shared payload, so the producer can keep its own Arc clone in addition to the copy carried by the handle.

pub fn data<T: Any + Send + Sync>(&self) -> Option<Arc<T>>

Downcasts the attached payload to T, returning a shared handle to it. Returns None when no payload is attached or it is of another type.

pub fn task_id(&self) -> &str

The background task’s identifier.

pub fn created_at(&self) -> u64

Wall-clock time in milliseconds (Unix epoch) when this handle, and thus the task, was created.

pub fn elapsed_ms(&self) -> u64

Milliseconds elapsed since the task was created, for observing its run time.

pub fn stop(&self)

Requests the producer stop this background task. Idempotent and safe to call after the task has already ended.

pub fn is_stopped(&self) -> bool

Returns whether a stop has already been requested for this task.

Trait Implementations

impl Clone for BackgroundHandle

fn clone(&self) -> BackgroundHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.