almost_enough/

lib.rs

//! # almost-enough
//!
//! Cooperative cancellation for Rust. Cancel long-running operations from another thread.
//!
//! ## Which Crate?
//!
//! - **Application code**: Use `almost-enough` (this crate) - has all implementations
//! - **Library code**: Depend on [`enough`](https://docs.rs/enough) (minimal) and accept `impl Stop`
//!
//! ## Complete Example
//!
//! ```rust
//! # #[cfg(feature = "alloc")]
//! # fn main() {
//! use almost_enough::{Stopper, Stop};
//! use std::thread;
//! use std::time::Duration;
//!
//! // 1. Create a stopper
//! let stop = Stopper::new();
//!
//! // 2. Clone and pass to worker thread
//! let worker_stop = stop.clone();
//! let handle = thread::spawn(move || {
//!     for i in 0..1000 {
//!         // 3. Check periodically - exit early if cancelled
//!         if worker_stop.should_stop() {
//!             return Err("cancelled");
//!         }
//!         // ... do work ...
//!         # std::hint::black_box(i);
//!     }
//!     Ok("completed")
//! });
//!
//! // 4. Cancel from main thread (or signal handler, timeout, etc.)
//! thread::sleep(Duration::from_millis(1));
//! stop.cancel();
//!
//! // Worker exits early
//! let result = handle.join().unwrap();
//! // result is either Ok("completed") or Err("cancelled")
//! # }
//! # #[cfg(not(feature = "alloc"))]
//! # fn main() {}
//! ```
//!
//! ## Quick Reference
//!
//! ```rust,no_run
//! # #[cfg(feature = "alloc")]
//! # fn main() {
//! # use almost_enough::{Stopper, Stop, StopReason};
//! # fn example() -> Result<(), StopReason> {
//! let stop = Stopper::new();
//! stop.cancel();              // Trigger cancellation
//! stop.should_stop();         // Returns true if cancelled
//! stop.check()?;              // Returns Err(StopReason) if cancelled
//! # Ok(())
//! # }
//! # }
//! # #[cfg(not(feature = "alloc"))]
//! # fn main() {}
//! ```
//!
//! ## Type Overview
//!
//! | Type | Feature | Use Case |
//! |------|---------|----------|
//! | [`Unstoppable`] | core | Zero-cost "never stop" |
//! | [`StopSource`] / [`StopRef`] | core | Stack-based, borrowed, zero-alloc |
//! | [`FnStop`] | core | Wrap any closure |
//! | [`OrStop`] | core | Combine multiple stops |
//! | [`Stopper`] | alloc | **Default choice** - Arc-based, clone to share |
//! | [`SyncStopper`] | alloc | Like Stopper, but every check is an Acquire load |
//! | [`ChildStopper`] | alloc | Hierarchical parent-child cancellation |
//! | [`StopToken`] | alloc | **Type-erased dynamic dispatch** - Arc-based, `Clone` |
//! | [`BoxedStop`] | alloc | Deprecated: use `StopToken` |
//! | [`WithTimeout`] | std | Add deadline to any `Stop` (reads the clock every check) |
//! | [`DebouncedTimeout`] | std | Like `WithTimeout`, reads the clock every N ≤ 64 checks, N timed from two checks |
//!
//! ## StopExt Extension Trait
//!
//! The [`StopExt`] trait adds combinator methods to any [`Stop`] implementation:
//!
//! ```rust
//! use almost_enough::{StopSource, Stop, StopExt};
//!
//! let timeout = StopSource::new();
//! let cancel = StopSource::new();
//!
//! // Combine: stop if either stops
//! let combined = timeout.as_ref().or(cancel.as_ref());
//! assert!(!combined.should_stop());
//!
//! cancel.cancel();
//! assert!(combined.should_stop());
//! ```
//!
//! ## Type Erasure with `StopToken`
//!
//! [`StopToken`] wraps `Arc<dyn Stop>` — it's `Clone` (cheap Arc increment),
//! type-erased, and can be sent across threads. [`Stopper`] and
//! [`SyncStopper`] convert to `StopToken` via `From`/`Into` without
//! allocating (the existing Arc is reused). A `Stopper` is then checked as a
//! direct atomic load, a `SyncStopper` through the vtable.
//!
//! Use [`CloneStop`] (a trait alias for `Stop + Clone + 'static`) to accept
//! any clonable stop, then erase with `into_token()` at the boundary:
//!
//! ```rust
//! # #[cfg(feature = "alloc")]
//! # fn main() {
//! use almost_enough::{CloneStop, StopToken, Stopper, Stop, StopExt};
//!
//! fn outer(stop: impl CloneStop) {
//!     // Erase the concrete type — StopToken is Clone
//!     let stop: StopToken = stop.into_token();
//!     inner(&stop);
//! }
//!
//! fn inner(stop: &StopToken) {
//!     let stop2 = stop.clone(); // cheap Arc increment
//!     // Only one version of this function exists
//!     while !stop.should_stop() {
//!         break;
//!     }
//! }
//!
//! let stop = Stopper::new();
//! outer(stop);
//! # }
//! # #[cfg(not(feature = "alloc"))]
//! # fn main() {}
//! ```
//!
//! ## Hierarchical Cancellation with `.child()`
//!
//! Create child stops that inherit cancellation from their parent:
//!
//! ```rust
//! # #[cfg(feature = "alloc")]
//! # fn main() {
//! use almost_enough::{Stopper, Stop, StopExt};
//!
//! let parent = Stopper::new();
//! let child = parent.child();
//!
//! // Child cancellation doesn't affect parent
//! child.cancel();
//! assert!(!parent.should_stop());
//!
//! // But parent cancellation propagates to children
//! let child2 = parent.child();
//! parent.cancel();
//! assert!(child2.should_stop());
//! # }
//! # #[cfg(not(feature = "alloc"))]
//! # fn main() {}
//! ```
//!
//! ## Stop Guards (RAII Cancellation)
//!
//! Automatically stop on scope exit unless explicitly disarmed:
//!
//! ```rust
//! # #[cfg(feature = "alloc")]
//! # fn main() {
//! use almost_enough::{Stopper, StopDropRoll};
//!
//! fn do_work(source: &Stopper) -> Result<(), &'static str> {
//!     let guard = source.stop_on_drop();
//!
//!     // If we return early or panic, source is stopped
//!     risky_operation()?;
//!
//!     // Success! Don't stop.
//!     guard.disarm();
//!     Ok(())
//! }
//!
//! fn risky_operation() -> Result<(), &'static str> {
//!     Ok(())
//! }
//!
//! let source = Stopper::new();
//! do_work(&source).unwrap();
//! # }
//! # #[cfg(not(feature = "alloc"))]
//! # fn main() {}
//! ```
//!
//! ## Feature Flags
//!
//! - **`std`** (default) - Full functionality including timeouts
//! - **`alloc`** - Arc-based types, `into_token()`, `child()`, `StopDropRoll`
//! - **None** - Core trait and stack-based types only

#![cfg_attr(not(feature = "std"), no_std)]
#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![warn(clippy::all)]

#[cfg(feature = "alloc")]
extern crate alloc;

// Re-export everything from enough
#[allow(deprecated)]
pub use enough::{Never, Stop, StopReason, Unstoppable};

/// Trait alias for stop tokens that can be cloned and sent across threads.
///
/// This is `Stop + Clone + 'static` — the minimum needed to clone a stop
/// token and send it to other threads. Since `Stop` already requires
/// `Send + Sync`, `CloneStop` types are fully thread-safe.
///
/// Use `impl CloneStop` in public API signatures when you need to clone
/// the stop token, then erase with [`StopToken`] internally:
///
/// ```rust
/// # #[cfg(feature = "alloc")]
/// # fn main() {
/// use almost_enough::{CloneStop, StopToken, Stop};
///
/// pub fn parallel_work(stop: impl CloneStop) {
///     let stop = StopToken::new(stop);
///     let s2 = stop.clone(); // Arc increment
/// }
/// # }
/// # #[cfg(not(feature = "alloc"))]
/// # fn main() {}
/// ```
pub trait CloneStop: Stop + Clone + 'static {}

/// Blanket implementation: any `Stop + Clone + 'static` is `CloneStop`.
impl<T: Stop + Clone + 'static> CloneStop for T {}

// Core modules (no_std, no alloc)
mod func;
mod or;
mod source;

pub use func::FnStop;
pub use or::OrStop;
pub use source::{StopRef, StopSource};

// Alloc-dependent modules
#[cfg(feature = "alloc")]
mod boxed;
#[cfg(feature = "alloc")]
mod stopper;
#[cfg(feature = "alloc")]
mod sync_stopper;
#[cfg(feature = "alloc")]
mod tree;

#[cfg(feature = "alloc")]
#[allow(deprecated)]
pub use boxed::BoxedStop;
#[cfg(feature = "alloc")]
mod stop_token;
#[cfg(feature = "alloc")]
pub use stop_token::StopToken;
#[cfg(feature = "alloc")]
pub use stopper::Stopper;
#[cfg(feature = "alloc")]
pub use sync_stopper::SyncStopper;
#[cfg(feature = "alloc")]
pub use tree::ChildStopper;

// Std-dependent modules
#[cfg(feature = "std")]
pub mod time;
#[cfg(feature = "std")]
pub use time::{DebouncedTimeout, DebouncedTimeoutExt, TimeoutExt, WithTimeout};

// Poll-latency instrumentation (opt-in: ~10-15ms compile cost, needs Instant)
#[cfg(feature = "poll-meter")]
mod meter;
#[cfg(feature = "poll-meter")]
pub use meter::{
    DEFAULT_FAST_GAP, DEFAULT_FLOOD_CALLS, DEFAULT_SLOW_GAP, HISTOGRAM_BUCKETS, PollMeter,
    PollProblem, PollReport, SiteReport,
};

// Cancel guard module
#[cfg(feature = "alloc")]
mod guard;
#[cfg(feature = "alloc")]
pub use guard::{CancelGuard, Cancellable, StopDropRoll};

/// Extension trait providing ergonomic combinators for [`Stop`] implementations.
///
/// This trait is automatically implemented for all `Stop + Sized` types.
///
/// # Example
///
/// ```rust
/// use almost_enough::{StopSource, Stop, StopExt};
///
/// let source_a = StopSource::new();
/// let source_b = StopSource::new();
///
/// // Combine with .or()
/// let combined = source_a.as_ref().or(source_b.as_ref());
///
/// assert!(!combined.should_stop());
///
/// source_b.cancel();
/// assert!(combined.should_stop());
/// ```
pub trait StopExt: Stop + Sized {
    /// Combine this stop with another, stopping if either stops.
    ///
    /// This is equivalent to `OrStop::new(self, other)` but with a more
    /// ergonomic method syntax that allows chaining.
    ///
    /// # Example
    ///
    /// ```rust
    /// use almost_enough::{StopSource, Stop, StopExt};
    ///
    /// let timeout = StopSource::new();
    /// let cancel = StopSource::new();
    ///
    /// let combined = timeout.as_ref().or(cancel.as_ref());
    /// assert!(!combined.should_stop());
    ///
    /// cancel.cancel();
    /// assert!(combined.should_stop());
    /// ```
    ///
    /// # Chaining
    ///
    /// Multiple sources can be chained:
    ///
    /// ```rust
    /// use almost_enough::{StopSource, Stop, StopExt};
    ///
    /// let a = StopSource::new();
    /// let b = StopSource::new();
    /// let c = StopSource::new();
    ///
    /// let combined = a.as_ref().or(b.as_ref()).or(c.as_ref());
    ///
    /// c.cancel();
    /// assert!(combined.should_stop());
    /// ```
    #[inline]
    fn or<S: Stop>(self, other: S) -> OrStop<Self, S> {
        OrStop::new(self, other)
    }

    /// Convert this stop into a [`BoxedStop`]. Deprecated: use
    /// [`into_token()`](StopExt::into_token), whose [`StopToken`] checks the
    /// same way and is `Clone`.
    #[cfg(feature = "alloc")]
    #[deprecated(
        since = "0.4.5",
        note = "use `into_token()`, whose `StopToken` checks the same way and is `Clone`"
    )]
    #[allow(deprecated)]
    #[inline]
    fn into_boxed(self) -> BoxedStop
    where
        Self: 'static,
    {
        BoxedStop::new(self)
    }

    /// Convert this stop into a shared, cloneable [`StopToken`].
    ///
    /// The result is `Clone` (via `Arc` increment) and can be sent across
    /// threads. Use this when you need owned, cloneable type erasure.
    ///
    /// If `self` is already a `StopToken`, this is a no-op (no double-wrapping).
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[cfg(feature = "alloc")]
    /// # fn main() {
    /// use almost_enough::{Stopper, StopToken, Stop, StopExt};
    ///
    /// let stop = Stopper::new();
    /// let dyn_stop: StopToken = stop.into_token();
    /// let clone = dyn_stop.clone(); // cheap Arc increment
    /// # }
    /// # #[cfg(not(feature = "alloc"))]
    /// # fn main() {}
    /// ```
    #[cfg(feature = "alloc")]
    #[inline]
    fn into_token(self) -> StopToken
    where
        Self: 'static,
    {
        StopToken::new(self)
    }

    /// Create a child stop that inherits cancellation from this stop.
    ///
    /// The returned [`ChildStopper`] will stop if:
    /// - Its own `cancel()` is called
    /// - This parent stop is cancelled
    ///
    /// Cancelling the child does NOT affect the parent.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[cfg(feature = "alloc")]
    /// # fn main() {
    /// use almost_enough::{Stopper, Stop, StopExt};
    ///
    /// let parent = Stopper::new();
    /// let child = parent.child();
    ///
    /// // Child cancellation is independent
    /// child.cancel();
    /// assert!(!parent.should_stop());
    /// assert!(child.should_stop());
    ///
    /// // Parent cancellation propagates
    /// let child2 = parent.child();
    /// parent.cancel();
    /// assert!(child2.should_stop());
    /// # }
    /// # #[cfg(not(feature = "alloc"))]
    /// # fn main() {}
    /// ```
    #[cfg(feature = "alloc")]
    #[inline]
    fn child(&self) -> ChildStopper
    where
        Self: Clone + 'static,
    {
        ChildStopper::with_parent(self.clone())
    }

    /// Wrap this stop in a [`PollMeter`] that records time between polls.
    ///
    /// For tests and perf investigations — see the `meter` module docs.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[cfg(feature = "poll-meter")]
    /// # fn main() {
    /// use almost_enough::{Stopper, Stop, StopExt};
    ///
    /// let meter = Stopper::new().metered();
    /// meter.check().unwrap();
    /// assert_eq!(meter.report().calls, 1);
    /// # }
    /// # #[cfg(not(feature = "poll-meter"))]
    /// # fn main() {}
    /// ```
    #[cfg(feature = "poll-meter")]
    #[inline]
    fn metered(self) -> PollMeter<Self> {
        PollMeter::new(self)
    }
}

// Blanket implementation for all Stop + Sized types
impl<T: Stop + Sized> StopExt for T {}

// Compile the READMEs' examples as doctests.
#[cfg(all(doctest, feature = "std"))]
#[doc = include_str!("../../../README.md")]
struct RootReadme;
#[cfg(all(doctest, feature = "std"))]
#[doc = include_str!("../README.md")]
struct CrateReadme;
// enough's README shows almost-enough's Stopper, so it compiles here.
#[cfg(all(doctest, feature = "std"))]
#[doc = include_str!("../../enough/README.md")]
struct EnoughReadme;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn or_extension_works() {
        let a = StopSource::new();
        let b = StopSource::new();
        let combined = a.as_ref().or(b.as_ref());

        assert!(!combined.should_stop());

        a.cancel();
        assert!(combined.should_stop());
    }

    #[test]
    fn or_chain_works() {
        let a = StopSource::new();
        let b = StopSource::new();
        let c = StopSource::new();

        let combined = a.as_ref().or(b.as_ref()).or(c.as_ref());

        assert!(!combined.should_stop());

        c.cancel();
        assert!(combined.should_stop());
    }

    #[test]
    fn or_with_unstoppable() {
        let source = StopSource::new();
        let combined = Unstoppable.or(source.as_ref());

        assert!(!combined.should_stop());

        source.cancel();
        assert!(combined.should_stop());
    }

    #[test]
    fn reexports_work() {
        // Verify that re-exports from enough work
        let _: StopReason = StopReason::Cancelled;
        let _ = Unstoppable;
        let source = StopSource::new();
        let _ = source.as_ref();
    }

    #[cfg(feature = "alloc")]
    #[test]
    #[allow(deprecated)] // Exercises the deprecated BoxedStop.
    fn alloc_reexports_work() {
        let stop = Stopper::new();
        let _ = stop.clone();
        let _ = BoxedStop::new(Unstoppable);
    }

    #[cfg(feature = "alloc")]
    #[test]
    #[allow(deprecated)] // Exercises the deprecated BoxedStop.
    fn into_boxed_works() {
        let stop = Stopper::new();
        let boxed: BoxedStop = stop.clone().into_boxed();

        assert!(!boxed.should_stop());

        stop.cancel();
        assert!(boxed.should_stop());
    }

    #[cfg(feature = "alloc")]
    #[test]
    #[allow(deprecated)] // Exercises the deprecated BoxedStop.
    fn into_boxed_with_unstoppable() {
        let boxed: BoxedStop = Unstoppable.into_boxed();
        assert!(!boxed.should_stop());
    }

    #[cfg(feature = "alloc")]
    #[test]
    #[allow(deprecated)] // Exercises the deprecated BoxedStop.
    fn into_boxed_prevents_monomorphization() {
        // This test verifies the pattern compiles correctly
        fn outer(stop: impl Stop + 'static) {
            inner(stop.into_boxed());
        }

        fn inner(stop: BoxedStop) {
            let _ = stop.should_stop();
        }

        let stop = Stopper::new();
        outer(stop);
        outer(Unstoppable);
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn child_extension_works() {
        let parent = Stopper::new();
        let child = parent.child();

        assert!(!child.should_stop());

        parent.cancel();
        assert!(child.should_stop());
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn child_independent_cancel() {
        let parent = Stopper::new();
        let child = parent.child();

        child.cancel();

        assert!(child.should_stop());
        assert!(!parent.should_stop());
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn child_chain() {
        let grandparent = Stopper::new();
        let parent = grandparent.child();
        let child = parent.child();

        grandparent.cancel();

        assert!(parent.should_stop());
        assert!(child.should_stop());
    }
}