Struct crossbeam_channel::Select

pub struct Select<'a> { /* private fields */ }

Selects from a set of channel operations.

Select 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.

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.

The select! macro is a convenience wrapper around Select. However, it cannot select over a dynamically created list of channel operations.

Examples

use std::thread;
use crossbeam_channel::{unbounded, Select};

let (s1, r1) = unbounded();
let (s2, r2) = unbounded();
s1.send(10).unwrap();

let mut sel = Select::new();
let oper1 = sel.recv(&r1);
let oper2 = sel.send(&s2);

// Both operations are initially ready, so a random one will be executed.
let oper = sel.select();
match oper.index() {
    i if i == oper1 => assert_eq!(oper.recv(&r1), Ok(10)),
    i if i == oper2 => assert_eq!(oper.send(&s2, 20), Ok(())),
    _ => unreachable!(),
}

Implementations

impl<'a> Select<'a>

pub fn new() -> Select<'a>

Creates an empty list of channel operations for selection.

Examples

use crossbeam_channel::Select;

let mut sel = Select::new();

// The list of operations is empty, which means no operation can be selected.
assert!(sel.try_select().is_err());

pub fn send<T>(&mut self, s: &'a Sender<T>) -> usize

Adds a send operation.

Returns the index of the added operation.

Examples

use std::thread;
use crossbeam_channel::{unbounded, Select};

let (s1, r1) = unbounded::<i32>();
let (s2, r2) = unbounded::<i32>();
let (s3, r3) = unbounded::<i32>();

let mut sel = Select::new();
let oper1 = sel.send(&s1);
let oper2 = sel.send(&s2);
let oper3 = sel.send(&s3);

assert_eq!(oper1, 0);
assert_eq!(oper2, 1);
assert_eq!(oper3, 2);

pub fn recv<T>(&mut self, r: &'a Receiver<T>) -> usize

Adds a receive operation.

Returns the index of the added operation.

Examples

use std::thread;
use crossbeam_channel::{unbounded, Select};

let (s1, r1) = unbounded::<i32>();
let (s2, r2) = unbounded::<i32>();
let (s3, r3) = unbounded::<i32>();

let mut sel = Select::new();
let oper1 = sel.recv(&r1);
let oper2 = sel.recv(&r2);
let oper3 = sel.recv(&r3);

assert_eq!(oper1, 0);
assert_eq!(oper2, 1);
assert_eq!(oper3, 2);

pub fn try_select(&mut self) -> Result<SelectedOperation<'_>, TrySelectError>

Attempts to execute one of the operations without blocking.

If an operation is ready, it is selected and returned. If multiple operations are ready at the same time, a random one among them is selected. If none of the operations are ready, an error is returned.

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.

The selected operation must be completed with SelectedOperation::send or SelectedOperation::recv.

Examples

use std::thread;
use crossbeam_channel::{unbounded, Select};

let (s1, r1) = unbounded();
let (s2, r2) = unbounded();

s1.send(10).unwrap();
s2.send(20).unwrap();

let mut sel = Select::new();
let oper1 = sel.recv(&r1);
let oper2 = sel.recv(&r2);

// Both operations are initially ready, so a random one will be executed.
let oper = sel.try_select();
match oper {
    Err(_) => panic!("both operations should be ready"),
    Ok(oper) => match oper.index() {
        i if i == oper1 => assert_eq!(oper.recv(&r1), Ok(10)),
        i if i == oper2 => assert_eq!(oper.recv(&r2), Ok(20)),
        _ => unreachable!(),
    }
}

pub fn select(&mut self) -> SelectedOperation<'_>

Blocks until one of the operations becomes ready.

Once an operation becomes ready, it is selected and returned.

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.

The selected operation must be completed with SelectedOperation::send or SelectedOperation::recv.

Panics

Panics if no operations have been added to Select.

Examples

use std::thread;
use std::time::Duration;
use crossbeam_channel::{unbounded, Select};

let (s1, r1) = unbounded();
let (s2, r2) = unbounded();

thread::spawn(move || {
    thread::sleep(Duration::from_secs(1));
    s1.send(10).unwrap();
});
thread::spawn(move || s2.send(20).unwrap());

let mut sel = Select::new();
let oper1 = sel.recv(&r1);
let oper2 = sel.recv(&r2);

// The second operation will be selected because it becomes ready first.
let oper = sel.select();
match oper.index() {
    i if i == oper1 => assert_eq!(oper.recv(&r1), Ok(10)),
    i if i == oper2 => assert_eq!(oper.recv(&r2), Ok(20)),
    _ => unreachable!(),
}

pub fn select_timeout(
    &mut self,
    timeout: Duration
) -> Result<SelectedOperation<'_>, SelectTimeoutError>

Waits until one of the operations becomes ready, but only for a limited time.

If an operation becomes ready, it is selected and returned. If multiple operations are ready at the same time, a random one among them is selected. If none of the operations become ready for the specified duration, an error is returned.

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.

The selected operation must be completed with SelectedOperation::send or SelectedOperation::recv.

Examples

use std::thread;
use std::time::Duration;
use crossbeam_channel::{unbounded, Select};

let (s1, r1) = unbounded();
let (s2, r2) = unbounded();

thread::spawn(move || {
    thread::sleep(Duration::from_secs(1));
    s1.send(10).unwrap();
});
thread::spawn(move || s2.send(20).unwrap());

let mut sel = Select::new();
let oper1 = sel.recv(&r1);
let oper2 = sel.recv(&r2);

// The second operation will be selected because it becomes ready first.
let oper = sel.select_timeout(Duration::from_millis(500));
match oper {
    Err(_) => panic!("should not have timed out"),
    Ok(oper) => match oper.index() {
        i if i == oper1 => assert_eq!(oper.recv(&r1), Ok(10)),
        i if i == oper2 => assert_eq!(oper.recv(&r2), Ok(20)),
        _ => unreachable!(),
    }
}

Trait Implementations

impl<'a> Clone for Select<'a>

fn clone(&self) -> Select<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Select<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Send for Select<'a>

impl<'a> Sync for Select<'a>