Struct PreemptiveCancellationToken 

pub struct PreemptiveCancellationToken { /* private fields */ }

Preemptive cancellation token.

Cloning is cheap – all clones share the same underlying state.

Implementations

impl PreemptiveCancellationToken

pub fn new() -> Self

Create a fresh, non-cancelled token.

pub fn cancel(&self)

Cancel immediately (cooperative – tasks must call check() or is_cancelled()).

pub fn cancel_with(&self, reason: impl Into<String>)

Cancel with a human-readable reason.

pub fn cancel_after(&self, after: Duration)

Schedule automatic cancellation after the given duration.

Spawns a lightweight watchdog thread that sleeps until the deadline, then atomically sets the cancelled flag. Returns immediately.

pub fn cancel_after_with(&self, after: Duration, reason: impl Into<String>)

Schedule automatic cancellation with a reason.

pub fn cancel_at(&self, deadline: Instant)

Schedule automatic cancellation at an absolute Instant.

pub fn deadline_guard(&self, budget: Duration) -> DeadlineGuard

Create a DeadlineGuard that cancels this token if dropped after the budget elapses. The token is also auto-cancelled via a watchdog thread, so even if the guard is never explicitly dropped, cancellation fires.

pub fn is_cancelled(&self) -> bool

true if the task has been cancelled/preempted.

pub fn check(&self) -> Result<(), Preempted>

Returns Ok(()) when not cancelled; Err(Preempted) otherwise.

Designed for use inside task loops:

token.check()?;

pub fn check_and_yield(&self) -> Result<(), Preempted>

Check and yield the current thread to the OS scheduler.

Useful in compute-bound loops – gives the runtime a chance to run the watchdog or other pending tasks, reducing observed cancellation latency without expensive system calls.

pub fn reset(&self)

Reset the token so it can be reused for a new task. Cancels any pending watchdog (watchdog will wake, see cancelled=true, then exit without re-setting because deadline_unix_ms is zeroed).

pub fn reason(&self) -> Option<String>

The reason supplied to cancel_with / cancel_after_with, if any.

pub unsafe fn install_signal_handler()

Install a per-process SIGUSR2 handler that sets a thread-local cancellation flag. Call once at program startup on Linux.

After installation, signal_preempt_thread(handle) will send SIGUSR2 to any thread, making its next check_signal() call return Err.

Safety

Installs a signal handler via libc. Safe if called at most once and not combined with other SIGUSR2 handlers.

pub fn signal_preempt_thread(pthread_id: pthread_t)

Send SIGUSR2 to a specific thread to trigger signal-based preemption.

The target thread must have called install_signal_handler() first.

pub fn check_signal() -> Result<(), Preempted>

Check the thread-local signal flag set by the SIGUSR2 handler.

Trait Implementations

impl Clone for PreemptiveCancellationToken

fn clone(&self) -> PreemptiveCancellationToken

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PreemptiveCancellationToken

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PreemptiveCancellationToken

fn default() -> Self

Returns the “default value” for a type.