# [−][src]Struct crossbeam_channel::Select

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

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.

Once a list of operations has been built with `Select`, there are two different ways of proceeding:

- Select an operation with `try_select`, `select`, or `select_timeout`. If successful, the returned selected operation has already begun and must be completed. If we don't complete it, a panic will occur.

- Wait for an operation to become ready with `try_ready`, `ready`, or `ready_timeout`. If successful, we may attempt to execute the operation, but are not obliged to. In fact, it's possible for another thread to make the operation not ready just before we try executing it, so it's wise to use a retry loop. However, note that these methods might return with success spuriously, so it's a good idea to always double check if the operation is really ready.

# Examples

Use `select` to receive a message from a list of receivers:

    use crossbeam_channel::{Receiver, RecvError, Select};

    fn recv_multiple<T>(rs: &[Receiver<T>]) -> Result<T, RecvError> {
        // Build a list of operations.
        let mut sel = Select::new();
        for r in rs {
            sel.recv(r);
        }

        // Complete the selected operation.
        let oper = sel.select();
        let index = oper.index();
        oper.recv(&rs[index])
    }

Use `ready` to receive a message from a list of receivers:

    use crossbeam_channel::{Receiver, RecvError, Select};

    fn recv_multiple<T>(rs: &[Receiver<T>]) -> Result<T, RecvError> {
        // Build a list of operations.
        let mut sel = Select::new();
        for r in rs {
            sel.recv(r);
        }

        loop {
            // Wait until a receive operation becomes ready and try executing it.
            let index = sel.ready();
            let res = rs[index].try_recv();

            // If the operation turns out not to be ready, retry.
            if let Err(e) = res {
                if e.is_empty() {
                    continue;
                }
            }

            // Success!
            return res.map_err(|_| RecvError);
        }
    }

## Methods

### `impl<'a> Select<'a>`[src]

#### `pub fn new() -> Select<'a>`[src]

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`[src]

Adds a send operation.

Returns the index of the added operation.

# Examples

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

    let (s, r) = unbounded::<i32>();

    let mut sel = Select::new();
    let index = sel.send(&s);

#### `pub fn recv<T>(&mut self, r: &'a Receiver<T>) -> usize`[src]

Adds a receive operation.

Returns the index of the added operation.

# Examples

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

    let (s, r) = unbounded::<i32>();

    let mut sel = Select::new();
    let index = sel.recv(&r);

#### `pub fn try_select(&mut self) -> Result<SelectedOperation<'a>, TrySelectError>`[src]

Attempts to select 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<'a>`[src]

Blocks until one of the operations becomes ready and selects it.

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

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<'a>, SelectTimeoutError>`[src]

Blocks for a limited time until one of the operations becomes ready and selects it.

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!(),
        }
    }

#### `pub fn try_ready(&mut self) -> Result<usize, TryReadyError>`[src]

Attempts to find a ready operation without blocking.

If an operation is ready, its index is returned. If multiple operations are ready at the same time, a random one among them is chosen. 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.

Note that this method might return with success spuriously, so it's a good idea to always double check if the operation is really ready.

# 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 chosen.
    match sel.try_ready() {
        Err(_) => panic!("both operations should be ready"),
        Ok(i) if i == oper1 => assert_eq!(r1.try_recv(), Ok(10)),
        Ok(i) if i == oper2 => assert_eq!(r2.try_recv(), Ok(20)),
        Ok(_) => unreachable!(),
    }

#### `pub fn ready(&mut self) -> usize`[src]

Blocks until one of the operations becomes ready.

Once an operation becomes ready, its index is returned. If multiple operations are ready at the same time, a random one among them is chosen.

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.

Note that this method might return with success spuriously, so it's a good idea to always double check if the operation is really ready.

# 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.
    match sel.ready() {
        i if i == oper1 => assert_eq!(r1.try_recv(), Ok(10)),
        i if i == oper2 => assert_eq!(r2.try_recv(), Ok(20)),
        _ => unreachable!(),
    }

#### `pub fn ready_timeout(
&mut self,
timeout: Duration
) -> Result<usize, ReadyTimeoutError>`[src]

Blocks for a limited time until one of the operations becomes ready.

If an operation becomes ready, its index is returned. If multiple operations are ready at the same time, a random one among them is chosen. 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.

Note that this method might return with success spuriously, so it's a good idea to double check if the operation is really ready.

# 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.
    match sel.ready_timeout(Duration::from_millis(500)) {
        Err(_) => panic!("should not have timed out"),
        Ok(i) if i == oper1 => assert_eq!(r1.try_recv(), Ok(10)),
        Ok(i) if i == oper2 => assert_eq!(r2.try_recv(), Ok(20)),
        Ok(_) => unreachable!(),
    }

## Trait Implementations

### `impl<'a> Send for Select<'a>`[src]

### `impl<'a> Default for Select<'a>`[src]

#### `fn default() -> Select<'a>`[src]

Returns the "default value" for a type. Read more

### `impl<'a> Sync for Select<'a>`[src]

### `impl<'a> Clone for Select<'a>`[src]

#### `fn clone(&self) -> Select<'a>`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0[src]

Performs copy-assignment from `source`. Read more

### `impl<'a> Debug for Select<'a>`[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`[src]

Formats the value using the given formatter. Read more

## Auto Trait Implementations

### `impl<'a> Unpin for Select<'a>`

### `impl<'a> !UnwindSafe for Select<'a>`

### `impl<'a> !RefUnwindSafe for Select<'a>`

## Blanket Implementations

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `fn to_owned(&self) -> T`[src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `fn clone_into(&self, target: &mut T)`[src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(self) -> U`[src]

Performs the conversion.

### `impl<T> From<T> for T`[src]

#### `fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)