//! Multi-producer multi-consumer channels for message passing.//! Multi-producer multi-consumer channels for message passing.

//!

//! This crate is an alternative to [`std::sync::mpsc`] with more features and better performance.

//!

//! # Hello, world!

//!

//! ```

//! use crossbeam_channel::unbounded;

//!

//! // Create a channel of unbounded capacity.

//! let (s, r) = unbounded();

//!

//! // Send a message into the channel.

//! s.send("Hello, world!").unwrap();

//!

//! // Receive the message from the channel.

//! assert_eq!(r.recv(), Ok("Hello, world!"));

//! ```

//!

//! # Channel types

//!

//! Channels can be created using two functions:

//!

//! * [`bounded`] creates a channel of bounded capacity, i.e. there is a limit to how many messages

//!   it can hold at a time.

//!

//! * [`unbounded`] creates a channel of unbounded capacity, i.e. it can hold any number of

//!   messages at a time.

//!

//! Both functions return a [`Sender`] and a [`Receiver`], which represent the two opposite sides

//! of a channel.

//!

//! Creating a bounded channel:

//!

//! ```

//! use crossbeam_channel::bounded;

//!

//! // Create a channel that can hold at most 5 messages at a time.

//! let (s, r) = bounded(5);

//!

//! // Can send only 5 messages without blocking.

//! for i in 0..5 {

//!     s.send(i).unwrap();

//! }

//!

//! // Another call to `send` would block because the channel is full.

//! // s.send(5).unwrap();

//! ```

//!

//! Creating an unbounded channel:

//!

//! ```

//! use crossbeam_channel::unbounded;

//!

//! // Create an unbounded channel.

//! let (s, r) = unbounded();

//!

//! // Can send any number of messages into the channel without blocking.

//! for i in 0..1000 {

//!     s.send(i).unwrap();

//! }

//! ```

//!

//! A special case is zero-capacity channel, which cannot hold any messages. Instead, send and

//! receive operations must appear at the same time in order to pair up and pass the message over:

//!

//! ```

//! use std::thread;

//! use crossbeam_channel::bounded;

//!

//! // Create a zero-capacity channel.

//! let (s, r) = bounded(0);

//!

//! // Sending blocks until a receive operation appears on the other side.

//! thread::spawn(move || s.send("Hi!").unwrap());

//!

//! // Receiving blocks until a send operation appears on the other side.

//! assert_eq!(r.recv(), Ok("Hi!"));

//! ```

//!

//! # Sharing channels

//!

//! Senders and receivers can be cloned and sent to other threads:

//!

//! ```

//! use std::thread;

//! use crossbeam_channel::bounded;

//!

//! let (s1, r1) = bounded(0);

//! let (s2, r2) = (s1.clone(), r1.clone());

//!

//! // Spawn a thread that receives a message and then sends one.

//! thread::spawn(move || {

//!     r2.recv().unwrap();

//!     s2.send(2).unwrap();

//! });

//!

//! // Send a message and then receive one.

//! s1.send(1).unwrap();

//! r1.recv().unwrap();

//! ```

//!

//! Note that cloning only creates a new handle to the same sending or receiving side. It does not

//! create a separate stream of messages in any way:

//!

//! ```

//! use crossbeam_channel::unbounded;

//!

//! let (s1, r1) = unbounded();

//! let (s2, r2) = (s1.clone(), r1.clone());

//! let (s3, r3) = (s2.clone(), r2.clone());

//!

//! s1.send(10).unwrap();

//! s2.send(20).unwrap();

//! s3.send(30).unwrap();

//!

//! assert_eq!(r3.recv(), Ok(10));

//! assert_eq!(r1.recv(), Ok(20));

//! assert_eq!(r2.recv(), Ok(30));

//! ```

//!

//! It's also possible to share senders and receivers by reference:

//!

//! ```

//! use crossbeam_channel::bounded;

//! use crossbeam_utils::thread::scope;

//!

//! let (s, r) = bounded(0);

//!

//! scope(|scope| {

//!     // Spawn a thread that receives a message and then sends one.

//!     scope.spawn(|_| {

//!         r.recv().unwrap();

//!         s.send(2).unwrap();

//!     });

//!

//!     // Send a message and then receive one.

//!     s.send(1).unwrap();

//!     r.recv().unwrap();

//! }).unwrap();

//! ```

//!

//! # Disconnection

//!

//! When all senders or all receivers associated with a channel get dropped, the channel becomes

//! disconnected. No more messages can be sent, but any remaining messages can still be received.

//! Send and receive operations on a disconnected channel never block.

//!

//! ```

//! use crossbeam_channel::{unbounded, RecvError};

//!

//! let (s, r) = unbounded();

//! s.send(1).unwrap();

//! s.send(2).unwrap();

//! s.send(3).unwrap();

//!

//! // The only sender is dropped, disconnecting the channel.

//! drop(s);

//!

//! // The remaining messages can be received.

//! assert_eq!(r.recv(), Ok(1));

//! assert_eq!(r.recv(), Ok(2));

//! assert_eq!(r.recv(), Ok(3));

//!

//! // There are no more messages in the channel.

//! assert!(r.is_empty());

//!

//! // Note that calling `r.recv()` does not block.

//! // Instead, `Err(RecvError)` is returned immediately.

//! assert_eq!(r.recv(), Err(RecvError));

//! ```

//!

//! # Blocking operations

//!

//! Send and receive operations come in three flavors:

//!

//! * Non-blocking (returns immediately with success or failure).

//! * Blocking (waits until the operation succeeds or the channel becomes disconnected).

//! * Blocking with a timeout (blocks only for a certain duration of time).

//!

//! A simple example showing the difference between non-blocking and blocking operations:

//!

//! ```

//! use crossbeam_channel::{bounded, RecvError, TryRecvError};

//!

//! let (s, r) = bounded(1);

//!

//! // Send a message into the channel.

//! s.send("foo").unwrap();

//!

//! // This call would block because the channel is full.

//! // s.send("bar").unwrap();

//!

//! // Receive the message.

//! assert_eq!(r.recv(), Ok("foo"));

//!

//! // This call would block because the channel is empty.

//! // r.recv();

//!

//! // Try receiving a message without blocking.

//! assert_eq!(r.try_recv(), Err(TryRecvError::Empty));

//!

//! // Disconnect the channel.

//! drop(s);

//!

//! // This call doesn't block because the channel is now disconnected.

//! assert_eq!(r.recv(), Err(RecvError));

//! ```

//!

//! # Iteration

//!

//! Receivers can be used as iterators. For example, method [`iter`] creates an iterator that

//! receives messages until the channel becomes empty and disconnected. Note that iteration may

//! block waiting for next message to arrive.

//!

//! ```

//! use std::thread;

//! use crossbeam_channel::unbounded;

//!

//! let (s, r) = unbounded();

//!

//! thread::spawn(move || {

//!     s.send(1).unwrap();

//!     s.send(2).unwrap();

//!     s.send(3).unwrap();

//!     drop(s); // Disconnect the channel.

//! });

//!

//! // Collect all messages from the channel.

//! // Note that the call to `collect` blocks until the sender is dropped.

//! let v: Vec<_> = r.iter().collect();

//!

//! assert_eq!(v, [1, 2, 3]);

//! ```

//!

//! A non-blocking iterator can be created using [`try_iter`], which receives all available

//! messages without blocking:

//!

//! ```

//! use crossbeam_channel::unbounded;

//!

//! let (s, r) = unbounded();

//! s.send(1).unwrap();

//! s.send(2).unwrap();

//! s.send(3).unwrap();

//! // No need to drop the sender.

//!

//! // Receive all messages currently in the channel.

//! let v: Vec<_> = r.try_iter().collect();

//!

//! assert_eq!(v, [1, 2, 3]);

//! ```

//!

//! # Selection

//!

//! The [`select!`] macro allows you to define a set of channel operations, wait until any one of

//! them becomes ready, and finally execute it. If multiple operations are ready at the same time,

//! a random one among them is selected.

//!

//! It is also possible to define a `default` case that gets executed if none of the operations are

//! ready, either right away or for a certain duration of time.

//!

//! An operation is considered to be ready if it doesn't have to block. Note that it is ready even

//! when it will simply return an error because the channel is disconnected.

//!

//! An example of receiving a message from two channels:

//!

//! ```

//! use std::thread;

//! use std::time::Duration;

//! use crossbeam_channel::{select, unbounded};

//!

//! let (s1, r1) = unbounded();

//! let (s2, r2) = unbounded();

//!

//! thread::spawn(move || s1.send(10).unwrap());

//! thread::spawn(move || s2.send(20).unwrap());

//!

//! // At most one of these two receive operations will be executed.

//! select! {

//!     recv(r1) -> msg => assert_eq!(msg, Ok(10)),

//!     recv(r2) -> msg => assert_eq!(msg, Ok(20)),

//!     default(Duration::from_secs(1)) => println!("timed out"),

//! }

//! ```

//!

//! If you need to select over a dynamically created list of channel operations, use [`Select`]

//! instead. The [`select!`] macro is just a convenience wrapper around [`Select`].

//!

//! # Extra channels

//!

//! Three functions can create special kinds of channels, all of which return just a [`Receiver`]

//! handle:

//!

//! * [`after`] creates a channel that delivers a single message after a certain duration of time.

//! * [`tick`] creates a channel that delivers messages periodically.

//! * [`never`](never()) creates a channel that never delivers messages.

//!

//! These channels are very efficient because messages get lazily generated on receive operations.

//!

//! An example that prints elapsed time every 50 milliseconds for the duration of 1 second:

//!

//! ```

//! use std::time::{Duration, Instant};

//! use crossbeam_channel::{after, select, tick};

//!

//! let start = Instant::now();

//! let ticker = tick(Duration::from_millis(50));

//! let timeout = after(Duration::from_secs(1));

//!

//! loop {

//!     select! {

//!         recv(ticker) -> _ => println!("elapsed: {:?}", start.elapsed()),

//!         recv(timeout) -> _ => break,

//!     }

//! }

//! ```

//!

//! [`send`]: Sender::send

//! [`recv`]: Receiver::recv

//! [`iter`]: Receiver::iter

//! [`try_iter`]: Receiver::try_iter

#![doc(test(

    no_crate_inject,

    attr(

        deny(warnings, rust_2018_idioms),

        allow(dead_code, unused_assignments, unused_variables)

    )

))]

#![warn(

    missing_docs,

    missing_debug_implementations,

    rust_2018_idioms,

    unreachable_pub

)]

#![cfg_attr(not(feature = "std"), no_std)]

// matches! requires Rust 1.42

#![allow(clippy::match_like_matches_macro)]

use cfg_if::cfg_if;

cfg_if! {

    if #[cfg(feature = "std")] {

        mod channel;

        mod context;

        mod counter;

        mod err;

        mod flavors;

        mod select;

        mod select_macro;

        mod utils;

        mod waker;

        /// Crate internals used by the `select!` macro.

        #[doc(hidden)]

        pub mod internal {

            pub use crate::select::SelectHandle;

            pub use crate::select::{select, select_timeout, try_select};

        }

        pub use crate::channel::{after, at, never, tick};

        pub use crate::channel::{bounded, unbounded};

        pub use crate::channel::{IntoIter, Iter, TryIter};

        pub use crate::channel::{Receiver, Sender};

        pub use crate::select::{Select, SelectedOperation};

        pub use crate::err::{ReadyTimeoutError, SelectTimeoutError, TryReadyError, TrySelectError};

        pub use crate::err::{RecvError, RecvTimeoutError, TryRecvError};

        pub use crate::err::{SendError, SendTimeoutError, TrySendError};

    }

}