Struct crossbeam_channel::select::Select
source · pub struct Select<'a> {
handles: Vec<(&'a dyn SelectHandle, usize, *const u8)>,
next_index: usize,
biased: bool,
}
Expand description
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
, orselect_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
, orready_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);
}
}
Fields§
§handles: Vec<(&'a dyn SelectHandle, usize, *const u8)>
A list of senders and receivers participating in selection.
next_index: usize
The next index to assign to an operation.
biased: bool
Whether to use the index of handles as bias for selecting ready operations.
Implementations§
source§impl<'a> Select<'a>
impl<'a> Select<'a>
sourcepub fn new() -> 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());
sourcepub fn new_biased() -> Self
pub fn new_biased() -> Self
Creates an empty list of channel operations with biased selection.
When multiple handles are ready, this will select the operation with the lowest index.
§Examples
use crossbeam_channel::Select;
let mut sel = Select::new_biased();
// The list of operations is empty, which means no operation can be selected.
assert!(sel.try_select().is_err());
sourcepub fn send<T>(&mut self, s: &'a Sender<T>) -> usize
pub fn send<T>(&mut self, s: &'a Sender<T>) -> usize
Adds a send operation.
Returns the index of the added operation.
§Examples
use crossbeam_channel::{unbounded, Select};
let (s, r) = unbounded::<i32>();
let mut sel = Select::new();
let index = sel.send(&s);
sourcepub fn recv<T>(&mut self, r: &'a Receiver<T>) -> usize
pub fn recv<T>(&mut self, r: &'a Receiver<T>) -> usize
Adds a receive operation.
Returns the index of the added operation.
§Examples
use crossbeam_channel::{unbounded, Select};
let (s, r) = unbounded::<i32>();
let mut sel = Select::new();
let index = sel.recv(&r);
sourcepub fn remove(&mut self, index: usize)
pub fn remove(&mut self, index: usize)
Removes a previously added operation.
This is useful when an operation is selected because the channel got disconnected and we want to try again to select a different operation instead.
If new operations are added after removing some, the indices of removed operations will not be reused.
§Panics
An attempt to remove a non-existing or already removed operation will panic.
§Examples
use crossbeam_channel::{unbounded, Select};
let (s1, r1) = unbounded::<i32>();
let (_, r2) = unbounded::<i32>();
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.select();
assert_eq!(oper.index(), oper2);
assert!(oper.recv(&r2).is_err());
sel.remove(oper2);
s1.send(10).unwrap();
let oper = sel.select();
assert_eq!(oper.index(), oper1);
assert_eq!(oper.recv(&r1), Ok(10));
sourcepub fn try_select(&mut self) -> Result<SelectedOperation<'a>, TrySelectError>
pub fn try_select(&mut self) -> Result<SelectedOperation<'a>, TrySelectError>
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 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!(),
}
}
sourcepub fn select(&mut self) -> SelectedOperation<'a>
pub fn select(&mut self) -> SelectedOperation<'a>
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!(),
}
sourcepub fn select_timeout(
&mut self,
timeout: Duration,
) -> Result<SelectedOperation<'a>, SelectTimeoutError>
pub fn select_timeout( &mut self, timeout: Duration, ) -> Result<SelectedOperation<'a>, SelectTimeoutError>
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!(),
}
}
sourcepub fn select_deadline(
&mut self,
deadline: Instant,
) -> Result<SelectedOperation<'a>, SelectTimeoutError>
pub fn select_deadline( &mut self, deadline: Instant, ) -> Result<SelectedOperation<'a>, SelectTimeoutError>
Blocks until a given deadline, or 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 before the given deadline, 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::{Instant, 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);
let deadline = Instant::now() + Duration::from_millis(500);
// The second operation will be selected because it becomes ready first.
let oper = sel.select_deadline(deadline);
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!(),
}
}
sourcepub fn try_ready(&mut self) -> Result<usize, TryReadyError>
pub fn try_ready(&mut self) -> Result<usize, TryReadyError>
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 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!(),
}
sourcepub fn ready(&mut self) -> usize
pub fn ready(&mut self) -> usize
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!(),
}
sourcepub fn ready_timeout(
&mut self,
timeout: Duration,
) -> Result<usize, ReadyTimeoutError>
pub fn ready_timeout( &mut self, timeout: Duration, ) -> Result<usize, ReadyTimeoutError>
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!(),
}
sourcepub fn ready_deadline(
&mut self,
deadline: Instant,
) -> Result<usize, ReadyTimeoutError>
pub fn ready_deadline( &mut self, deadline: Instant, ) -> Result<usize, ReadyTimeoutError>
Blocks until a given deadline, or 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 before the deadline, 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, Instant};
use crossbeam_channel::{unbounded, Select};
let deadline = Instant::now() + Duration::from_millis(500);
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_deadline(deadline) {
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 Send for Select<'_>
impl Sync for Select<'_>
Auto Trait Implementations§
impl<'a> Freeze for Select<'a>
impl<'a> !RefUnwindSafe for Select<'a>
impl<'a> Unpin for Select<'a>
impl<'a> !UnwindSafe for Select<'a>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)