Cargo.toml
www/index.md
www/changelog.md
src/lib.rs
src/pair.rs
src/pair/killtrig.rs
src/pair/killwait.rs
examples/tokselect.rs

[package]
name = "killswitch"
version = "0.4.2"
authors = ["Jan Danielsson <jan.danielsson@qrnch.com>"]
edition = "2021"
license = "0BSD"
categories = [ "asynchronous" ]
keywords = [ "shutdown", "async"  ]
repository = "https://repos.qrnch.tech/pub/killswitch"
description = "Killswitch used to broadcast a shutdown request."

[dependencies]
parking_lot = { version = "0.12.1" }

[dev-dependencies]
tokio = { version = "1.32.0", features = [
  "macros", "rt-multi-thread", "time"
] }
tokio-test = { version = "0.4.3" }
tracing = { version = "0.1.37" }
tracing-subscriber = { version = "0.3.17" }

[package.metadata.docs.rs]
rustdoc-args = ["--generate-link-to-definition"]

//! This library provides two separate structures for signalling (and
//! receiveing) termination requests [in `async` contexts]:
//!
//! - [`KillSwitch`] acts as both a trigger and a receiver.
//! - [`pair::KillTrig`] and [`pair::KillWait`] (created using
//!   [`pair::create()`]) act as a kill signal sender and receiver.
//!
//! # KillSwitch
//! Signal a request for (multiple) async tasks to self-terminate.
//!
//! ```
//! use std::error::Error;
//! use tokio::time::{sleep, Duration};
//! use killswitch::KillSwitch;
//!

  pub fn wait(&self) -> WaitFuture {
    WaitFuture {
      ctx: Arc::clone(&self.0),
      id: None
    }
  }


  /// Return a Future that will return `Ready` once there are no more waiters
  /// waiting on this killswitch to be triggered.
  ///
  /// The KillSwitch must be triggered before calling this function, or the
  /// returned future will return an error.
  pub fn finalize(&self) -> FinalizedFuture {
    FinalizedFuture {
      ctx: Arc::clone(&self.0),
      id: None
    }
  }

  /// Reset `KillSwitch`.
  ///
  /// Care should be taken when using this.  Generally speaking it should only
  /// be used immediately following a [`KillSwitch::finalize()`]:
  ///
  /// ```
  /// use killswitch::KillSwitch;
  ///
  /// # tokio_test::block_on(async {
  /// let ks = KillSwitch::default();
  /// assert_eq!(ks.is_triggered(), false);
  ///
  /// // Trigger kill switch
  /// ks.trigger();
  /// assert_eq!(ks.is_triggered(), true);
  /// ks.finalize().await;
  /// ks.reset();
  ///
  /// // KillSwitch became untriggered again
  /// assert_eq!(ks.is_triggered(), false);
  /// # });
  /// ```
  ///
  /// Applications should prefer to call [`KillSwitch::finalize_reset()`]
  /// rather than calling `finalize()` and `reset()`.
  pub fn reset(&self) {
    self.0.triggered.store(false, Ordering::SeqCst);
  }

  /// Finalize and reset `KillSwitch`.
  ///
  /// Returns `Err(())` if the `KillSwitch` wasn't in triggered state.
  pub async fn finalize_reset(&self) -> Result<(), ()> {
    if (self.finalize().await).is_ok() {
      self.reset();
      Ok(())
    } else {
      Err(())
    }
  }

  /// Return a boolean indicating whether kill switch has been triggered.
  ///
  /// Returns `true` if kill switch has been triggered.  Returns `false`
  /// otherwise.
  pub fn is_triggered(&self) -> bool {
    self.0.triggered.load(Ordering::SeqCst)

# Change Log

## [Unreleased]

### Added

### Changed

### Removed

---

## [0.4.2] - 2023-09-17

[Details](https://repos.qrnch.tech/pub/killswitch/vdiff?from=killswitch-0.4.1&to=killswitch-0.4.2)

### Added

- Add `KillSwitch::reset()` and `KillSwitch::finalize_reset()` to allow a kill
  switch to be reused.

# killswitch

The killswitch is a special-purpose object for signalling multiple tasks
simultaneously that they should self-terminate.


## Change log

The details of changes can always be found in the timeline, but for a
high-level view of changes between released versions there's a manually
maintained [Change Log](./changelog.md).


## Project Status

_killswitch_ is in _maintenance mode_; it is feature-complete with regards to
its initial goal, but will receive bugfixes and improvements to
implementation/documentation.