tchannel/
lib.rs

1// Copyright 2017 Thomas de Zeeuw
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT
5// or http://opensource.org/licenses/MIT>, at your option. This file may not be
6// used, copied, modified, or distributed except according to those terms.
7
8//! Optimized channels for Rust. This crate contains verious version of the same
9//! concept, channels. The available versions are:
10//!
11//! - oneshot, allows a single value to be send and received.
12//! - mpsc, allows for multiple producers (senders) and a single consumer
13//! (receiver).
14//!
15//! All these different versions work in the same way. All modules will have a
16//! `channel` function which returns a `Sender` and a `Receiver`. The `Sender`
17//! can only send values and the `Receiver` can only receive values. The remaing
18//! API are errors, which are a bit more channel version specific, and adapters
19//! for the `futures` crate, see [below](#futures).
20//!
21//! # Example
22//!
23//! We'll use the oneshot channel for this example, but all versions will have
24//! roughly the same type and structure setup.
25//!
26//! ```
27//! # extern crate tchannel;
28//! # fn main() {
29//! use tchannel::oneshot::{channel, Sender, Receiver, ReceiveError};
30//!
31//! // Create a new channel, which has a sender and a receiver.
32//! let (sender, receiver): (Sender<_>, Receiver<_>) = channel();
33//!
34//! // First we'll try to receive a value, but the channel should be empty so
35//! // it will return an error. We can recover the receiver (`try_receive`
36//! // consumes `Receiver` in case of an oneshot channel) via the `Empty` error.
37//! let receiver = match receiver.try_receive() {
38//!     Err(ReceiveError::Empty(receiver)) => receiver,
39//!     _ => panic!("expected the channel to be empty"),
40//! };
41//!
42//! // Now we'll send our value along the channel. In case of a oneshot channel
43//! // this will consume the `Sender`.
44//! //
45//! // This will only return an error if the receiving side of the channel is
46//! // disconnected, in which case it will return a `SendError` which allows
47//! // the send value to retrieved.
48//! assert_eq!(sender.send("Hello world"), Ok(()));
49//!
50//! // Here we'll receive the value, making sure it's the same as what we send.
51//! assert_eq!(receiver.try_receive().unwrap(), "Hello world");
52//! # }
53//! ```
54//!
55//! # Futures
56//!
57//! Support for the [`futures`] crate is available if the `with-futures` feature
58//! is enabled (disabled by default).
59//!
60//! TODO: add example usage.
61//!
62//! [`futures`]: https://crates.io/crates/futures
63
64#![warn(missing_docs)]
65#![warn(missing_debug_implementations)]
66#![warn(unused_results)]
67
68#[cfg(feature = "futures")]
69extern crate futures;
70
71mod atomic_arc;
72mod atomic_cell;
73
74pub mod mpsc;
75pub mod oneshot;
76
77/// This error will be returned if the receiving side of the channel is
78/// disconnected, while trying to send a value across the channel.
79#[derive(Debug, Copy, Clone, Eq, PartialEq)]
80pub struct SendError<T>(pub T);
81
82/// The error returned by trying to receive a value.
83#[derive(Debug, Copy, Clone, Eq, PartialEq)]
84pub enum ReceiveError {
85    /// The channel is empty, more values are possible.
86    Empty,
87    /// The channel is empty and the sending side of the channel is
88    /// disconnected, which means that no more values are coming.
89    Disconnected,
90}
tchannel/lib.rs

tchannel/
lib.rs
