//! Channels with manual control about state allocation.
//!
//! The functionality provided in this module is equivalent to that in [`ufotofu::channels`](crate::channels), except that the APIs here offer greater control about memory management. More specifically, channel creation in this module always takes a cloneable reference (`Ref: Deref<Target = State> + Clone`) to an opaque `State` type as an argument. You can allocate this state wherever you want. The more convenient APIs in [`ufotofu::channels`](crate::channels) internally allocate their state in an `Rc`. But with this module, you can allocate the state, for example, on the stack:
//!
//! ```
//! use futures::join;
//! use ufotofu::prelude::*;
//! use ufotofu::channels::advanced::sssr::*;
//!
//! // Allocate a new opaque state on the stack.
//! let state = State::new(ufotofu::queues::new_static::<i16, 2>());
//!
//! // Create a channel whose endpoints reference the shared state through vanilla reference.
//! // The state must outlive the endpoints, otherwise you would get a compiler error.
//! let (mut sender, mut receiver) = new_sssr(&state);
//!
//! 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);
//! });
//! ```
pub mod sssr;
pub use sssr::new_sssr;