Struct ChildStopper 

pub struct ChildStopper { /* private fields */ }

A cancellation primitive with tree-structured parent-child relationships.

ChildStopper uses a unified clone model: clone to share, any clone can cancel. When cancelled, it does NOT affect its parent or siblings - only this node and any of its children.

Example

use almost_enough::{ChildStopper, Stop};

let parent = ChildStopper::new();
let child = parent.child();

// Clone to share across threads
let child_clone = child.clone();

// Any clone can cancel
child_clone.cancel();
assert!(child.should_stop());

// Parent is not affected
assert!(!parent.should_stop());

Performance

• Size: 8 bytes (one pointer)
• check(): per level of the tree, a state byte and a parent pointer, with no vtable call. A parent that isn’t a ChildStopper is checked once, at the top of the chain, as a StopToken would check it.

Implementations

impl ChildStopper

pub fn new() -> Self

Create a new root tree node (no parent).

This creates a tree root that can have children added via child().

Example

use almost_enough::{ChildStopper, Stop};

let root = ChildStopper::new();
let child = root.child();

root.cancel();
assert!(child.should_stop());

pub fn with_parent<T: Stop + 'static>(parent: T) -> Self

Create a new tree node with a parent.

The child will stop if either:

• cancel() is called on this node (or any clone)
• Any ancestor in the parent chain is cancelled

Example

use almost_enough::{Stopper, ChildStopper, Stop};

let root = Stopper::new();
let child = ChildStopper::with_parent(root.clone());

root.cancel();
assert!(child.should_stop());

pub fn child(&self) -> ChildStopper

Create a child of this tree node.

The child will stop if either this node or any ancestor is cancelled. Cancelling the child does NOT affect this node.

Example

use almost_enough::{ChildStopper, Stop};

let parent = ChildStopper::new();
let child = parent.child();
let grandchild = child.child();

child.cancel();
assert!(!parent.should_stop());  // Parent unaffected
assert!(child.should_stop());
assert!(grandchild.should_stop());  // Inherits from parent

pub fn cancel(&self)

Cancel this node (and all its children).

This does NOT affect the parent or siblings. A Release swap: writes made before a cancel() of this node are visible to a thread whose is_cancelled returns true after it.

pub fn is_cancelled(&self) -> bool

Check if this node is cancelled (either directly or via ancestor).

When it returns true, an Acquire fence follows, so this thread also sees the writes made before whichever cancel() it observed (for a parent that isn’t a ChildStopper, if that parent’s cancel is a Release swap or store, as every stop in this crate’s is). Checks are Relaxed.

Trait Implementations

impl Cancellable for ChildStopper

fn stop(&self)

Request stop/cancellation.

impl Clone for ChildStopper

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ChildStopper

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

Formats the value using the given formatter.

impl Default for ChildStopper

fn default() -> Self

Returns the “default value” for a type.

impl Stop for ChildStopper

fn check(&self) -> Result<(), StopReason>

Check if the operation should stop.

fn should_stop(&self) -> bool

Returns true if the operation should stop.

fn may_stop(&self) -> bool

Returns true if this stop can ever signal a stop.