//! In-memory FIFO queue communication primitives.
//!
//! This module provides FIFO in-memory communiction channels, to let some part of a program asynchronously deliver data to another part of a program. The entrypoint for working with channels is always a channel creation function, which returns a *sender* and a *receiver*. The sender is a bulk consumer, and the receiver is a bulk producer, producing all items which the sender consumed.
//!
//! Before the items consumed by a sender are produced by a receiver, they are placed in a buffer. This buffer is supplied at channel creation time, and can be any value implementing the [`Queue`](crate::queues::Queue) trait.
//!
//! If the sender type for a channel implements [`Clone`], the channel can be written to from multiple parts of a codebase. If the sender does not implement [`Clone`], there is only a single location in a codebase that can write to the channel. Likewise, the receiver implementing [`Clone`] determines the flexibility in reading from the channel. We call a channel with a clonable sender a "multi-sender" channel, as opposed to a "single-sender" channel. Analogously, we speak of "multi-receiver" and "single-receiver" channels. The wider Rust ecosystem (including the standard library) speaks of "multi-producer" or "single-consumer" channels; we sidestep that terminology to avoid confusion with the ufootfu meaning of "producer" and "consumer".
//!
//! ```
//! # #[cfg(feature = "std")] {
//! use futures::join;
//! use ufotofu::prelude::*;
//! use ufotofu::channels::sssr::*;
//!
//! // Create the channel, using a queue of capacity two.
//! let (mut sender, mut receiver) = new_sssr(ufotofu::queues::new_fixed::<i16>(2));
//!
//! pollster::block_on(async {
//! // A future sending three items to the channel, then closing.
//! let send_things = async {
//! assert!(sender.consume_item(300).await.is_ok());
//! assert!(sender.consume_item(400).await.is_ok());
//! assert!(sender.consume_item(500).await.is_ok());
//! assert!(sender.consume_final(-17).await.is_ok());
//! };
//!
//! // A future receiving the items from the channel.
//! let receive_things = async {
//! assert_eq!(300, receiver.produce().await.unwrap().unwrap_left());
//! assert_eq!(400, receiver.produce().await.unwrap().unwrap_left());
//! assert_eq!(500, receiver.produce().await.unwrap().unwrap_left());
//! assert_eq!(-17, receiver.produce().await.unwrap().unwrap_right());
//! };
//!
//! // Concurrently send and receive the items. Concurrency is necessary, because
//! // the number of transmitted items exceeds the maximum capacity of the queue we use.
//! join!(receive_things, send_things);
//! });
//! # }
//! ```
//!
//! In the wider Rust ecosystems, channels with clonable *senders are called "multi-producer" channels. We call them "multi-sender" channels, to avoid confusion with the special meaning of "producer" in ufotofu. Analogously, we speak of "multi-receiver"
//!
//! The channel implementations here allocate some shared state on the heap. See the [`advanced`] module if you need more control over how that state is allocated, and in particular if you want to store it on the stack.
pub mod advanced;
#[cfg(feature = "std")]
pub mod sssr;
#[cfg(feature = "std")]
pub use sssr::new_sssr;