[package]
name = "limqch"
version = "0.2.2"
edition = "2024"
license = "0BSD"
# https://crates.io/category_slugs
categories = [ "concurrency" ]
keywords = [ "channel", "bounded" ]
repository = "https://repos.qrnch.tech/pub/limqch"
description = "A channel built on top of limq."

]

# https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section
[badges]
maintenance = { status = "actively-developed" }

[dependencies]
limq = { version = "0.4.0" }
parking_lot = { version = "0.12.3" }
wakerizer = { version = "0.1.0" }

[dev-dependencies]
tokio = { version = "1.44.2", features = ["macros", "rt", "rt-multi-thread"] }

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

[lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }
nursery = { level = "warn", priority = -1 }
cargo = { level = "warn", priority = -1 }

cargo_common_metadata = "allow"

  ///
  /// If the channel has a limit, and the limit has been reached, then block
  /// and wait until a [`Receiver`](super::Receiver) has make more room
  /// available on the queue.
  ///
  /// # Errors
  /// [`Error::CantFit`] means the [`Controller`] rejected the node.
  /// [`Error::Closed`] means no [`Receiver`](super::Receiver)s remain.
  pub async fn send_async(&self, mut n: T) -> Result<(), Error<T>> {
    // In an ideal world, there'd be a SendFuture that takes in the new node.
    // However, if the queue is full the node needs to be stored somewhere
    // until the task is woken up, and this presents a few annoying challenges.
    //
    // Instead, we'll use a Future that simply waits for there to be space
    // available and when that resolves immediate all the node to the queue.

  /// Forcibly add an element to the queue.
  ///
  /// If the queue has a limit and the queue is full, then the oldest node will
  /// be removed before the new element is added.
  ///
  /// # Errors
  /// [`Error::CantFit`] means the [`Controller`] rejected the node.
  /// [`Error::Closed`] means no [`Receiver`](super::Receiver)s remain.
  pub fn force_send(&self, n: T) -> Result<(), Error<T>> {
    let mut inner = self.sh.inner.lock();
    let _ = inner.q.force_push(n);
    drop(inner);

    // Have a new element in queue -- wake up a waiting receiver
    self.sh.wake_receivers();

    Ok(())
  }

  /// Forcibly add an element to rhe channel, allowing the caller to determine
  /// how overflow is handled.
  ///
  /// # Errors
  /// [`Error::CantFit`] means the [`Controller`] rejected the node.
  /// [`Error::Closed`] means no [`Receiver`](super::Receiver)s remain.
  pub fn force_send_oc(
    &self,
    n: T,
    overflow: Overflow
  ) -> Result<(), Error<T>> {
    let mut inner = self.sh.inner.lock();
    let _ = inner.q.force_push_oc(n, overflow)?;
    drop(inner);

    // Have a new element in queue -- wake up a waiting receiver
    self.sh.wake_receivers();

    Ok(())
  }

# Change Log

⚠️  indicates a breaking change.

## [Unreleased]

[Details](/vdiff?from=limqch-0.2.1&to=trunk)

### Added

### Changed

- Use `limq` `0.4.0`.

### Removed

---

## [0.2.1] - 2025-04-12