Crate channels

Sender/Receiver types to be used with any type that implements std::io::Read and std::io::Write.

This crate is similar to std::sync::mpsc in terms of the API, and most of the documentation for that module carries over to this crate.

An important note, when an object is sent through a Sender, which was passed into channel(), for other code of the same or another process to use it.

Don’t think of these channels as a replacement for std::sync::mpsc, but as another implementation that works over many different transports.

These channels are meant to be used in combination with network sockets, local sockets, pipes, etc. And can be chained with other adapter types to create complex and structured packets.

The differences are:

• Channels will block, unless the underlying stream is set as non-blocking.
• The amount of messages that can be queued up before reading is dependent on the underlying stream.
• By default, the Sender and Receiver types cannot be sent across threads, unless the mt feature is enabled.

Examples

Simple echo server:

use std::io;
use std::net::TcpListener;

use channels;

fn main() -> io::Result<()> {
	let listener = TcpListener::bind("0.0.0.0:1337")?;

	loop {
		let (stream, _) = listener.accept()?;
		let (mut tx, mut rx) = channels::channel::<i32, _>(stream);

		let client_data = rx.recv()?;

		println!("Client sent: {}", client_data);

		tx.send(client_data)?;
	}

	Ok(())
}

Simple echo client:

use std::io;
use std::net::TcpStream;

fn main() -> io::Result<()> {
	let stream = TcpStream::connect("127.0.0.1:1337")?;
	let (mut tx, mut rx) = channels::channel::<i32, _>(stream);

	tx.send(1337_i32)?;

	let received_data = rx.recv()?;

	assert_eq!(received_data, 1337_i32);

	Ok(())
}

Multi-threaded echo server:

use std::io;
use std::net::TcpListener;

fn main() -> io::Result<()> {
	let listener = TcpListener::bind("0.0.0.0:1337")?;

	loop {
		let (stream, _) = listener.accept()?;

		std::thread::spawn(move || {
			let (mut tx, mut rx) = channels::channel::<i32, _>(stream);

			loop {
				let client_data = rx.recv().unwrap();

				println!("Client sent: {}", client_data);

				tx.send(client_data).unwrap();
			}
		});
	}

	Ok(())
}

Send/Recv with 2 threads:

use std::io;
use std::net::TcpStream;

fn main() -> io::Result<()> {
	let stream = TcpStream::connect("127.0.0.1:1337")?;
	let (mut tx, mut rx) = channels::channel::<i32, _>(stream);

	// Receiving thread
	let recv_thread = std::thread::spawn(move || loop {
		println!("Received: {}", rx.recv().unwrap());
	});

	// Sending thread
	let send_thread = std::thread::spawn(move || {
		let mut counter: i32 = 0;
		loop {
			tx.send(counter).unwrap();
			counter += 1;
		}
	});

	recv_thread.join().unwrap();
	send_thread.join().unwrap();

	Ok(())
}

Structs

Receiver

The receiving-half of the channel. This is the same as std::sync::mpsc::Receiver, except for a few key differences.

Sender

The sending-half of the channel. This is the same as std::sync::mpsc::Sender, except for a few key differences.

Functions

channel

Creates a new channel, returning the sender/receiver. This is the same as std::sync::mpsc::channel().