Crossbeam Channel

https://docs.rs/crossbeam-channel/latest
Admin
Crossbeam Channel is a multi-producer multi-consumer message passing library for Rust that provides...
Tokens:125,607
Snippets:1,041
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Select operations

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/select.rs.html

Example showing the setup of multiple send and receive operations within a Select instance.

```rust
use crossbeam_channel::{bounded, Select};

let (s1, r1) = bounded::<()>(0);
let (s2, r2) = bounded::<()>(0);
let (s3, r3) = bounded::<()>(1);

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

--------------------------------

### Bounded channel usage examples

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.bounded.html?search=u32+-%3E+bool

Demonstrates usage of bounded channels with capacity 1 and zero-capacity rendezvous channels.

```rust
use std::thread;
use std::time::Duration;
use crossbeam_channel::bounded;

let (s, r) = bounded(1);

// This call returns immediately because there is enough space in the channel.
s.send(1).unwrap();

thread::spawn(move || {
    // This call blocks the current thread because the channel is full.
    // It will be able to complete only after the first message is received.
    s.send(2).unwrap();
});

thread::sleep(Duration::from_secs(1));
assert_eq!(r.recv(), Ok(1));
assert_eq!(r.recv(), Ok(2));
```

```rust
use std::thread;
use std::time::Duration;
use crossbeam_channel::bounded;

let (s, r) = bounded(0);

thread::spawn(move || {
    // This call blocks the current thread until a receive operation appears
    // on the other side of the channel.
    s.send(1).unwrap();
});

thread::sleep(Duration::from_secs(1));
assert_eq!(r.recv(), Ok(1));
```

--------------------------------

### Channel Selection Example

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/lib.rs.html

Demonstrates how to use the select! macro to coordinate between a ticker channel and a timeout channel.

```APIDOC
## select!

### Description
The `select!` macro allows a thread to wait on multiple channel operations simultaneously. It blocks until one of the operations can be completed.

### Usage
```rust
use std::time::{Duration, Instant};
use crossbeam_channel::{after, select, tick};

let start = Instant::now();
let ticker = tick(Duration::from_millis(50));
let timeout = after(Duration::from_secs(1));

loop {
    select! {
        recv(ticker) -> _ => println!("elapsed: {:?}", start.elapsed()),
        recv(timeout) -> _ => break,
    }
}
```
```

--------------------------------

### Partial Blocking Iterator Example

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/channel.rs.html?search=u32+-%3E+bool

A truncated example showing the initialization of a blocking iterator.

```rust
use std::thread;
use crossbeam_channel::unbounded;

let (s, r) = unbounded();

thread::spawn(move || {
    s.send(1).unwrap();
```

--------------------------------

### Implement Channel Operations

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/zero.rs.html

Core methods for initializing channels and managing the start of send/receive operations.

```rust
impl<T> Channel<T> {
    /// Constructs a new zero-capacity channel.
    pub(crate) fn new() -> Self {
        Channel {
            inner: Mutex::new(Inner {
                senders: Waker::new(),
                receivers: Waker::new(),
                is_disconnected: false,
            }),
            _marker: PhantomData,
        }
    }

    /// Returns a receiver handle to the channel.
    pub(crate) fn receiver(&self) -> Receiver<'_, T> {
        Receiver(self)
    }

    /// Returns a sender handle to the channel.
    pub(crate) fn sender(&self) -> Sender<'_, T> {
        Sender(self)
    }

    /// Attempts to reserve a slot for sending a message.
    fn start_send(&self, token: &mut Token) -> bool {
        let mut inner = self.inner.lock();

        // If there's a waiting receiver, pair up with it.
        if let Some(operation) = inner.receivers.try_select() {
            token.zero.0 = operation.packet;
            true
        } else if inner.is_disconnected {
            token.zero.0 = ptr::null_mut();
            true
        } else {
            false
        }
    }

    /// Writes a message into the packet.
    pub(crate) unsafe fn write(&self, token: &mut Token, msg: T) -> Result<(), T> {
        // If there is no packet, the channel is disconnected.
        if token.zero.0.is_null() {
            return Err(msg);
        }

        let packet = &*(token.zero.0 as *const Packet<T>);
        packet.msg.get().write(Some(msg));
        packet.ready.store(true, Ordering::Release);
        Ok(())
    }

    /// Attempts to pair up with a sender.
    fn start_recv(&self, token: &mut Token) -> bool {
        let mut inner = self.inner.lock();

```

--------------------------------

### Start Send Operation

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/array.rs.html

Attempts to reserve a slot for sending a message, using a backoff strategy.

```rust
fn start_send(&self, token: &mut Token) -> bool {
    let backoff = Backoff::new();
    let mut tail = self.tail.load(Ordering::Relaxed);

    loop {
```

--------------------------------

### Start receiving from channel

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/array.rs.html?search=

Attempts to reserve a slot for receiving by atomically updating the head pointer. It checks if the slot is ready to be popped based on the stamp.

```rust
    /// Attempts to reserve a slot for receiving a message.
    fn start_recv(&self, token: &mut Token) -> bool {
        let backoff = Backoff::new();
        let mut head = self.head.load(Ordering::Relaxed);

        loop {
            // Deconstruct the head.
            let index = head & (self.mark_bit - 1);
            let lap = head & !(self.one_lap - 1);

            // Inspect the corresponding slot.
            debug_assert!(index < self.buffer.len());
            let slot = unsafe { self.buffer.get_unchecked(index) };
            let stamp = slot.stamp.load(Ordering::Acquire);

            // If the stamp is ahead of the head by 1, we may attempt to pop.
            if head + 1 == stamp {
                let new = if index + 1 < self.cap {
                    // Same lap, incremented index.
                    // Set to `{ lap: lap, mark: 0, index: index + 1 }`.
                    head + 1
                } else {
                    // One lap forward, index wraps around to zero.
                    // Set to `{ lap: lap.wrapping_add(1), mark: 0, index: 0 }`.
                    lap.wrapping_add(self.one_lap)
                };

                // Try moving the head.
                match self.head.compare_exchange_weak(
                    head,
                    new,
                    Ordering::SeqCst,
                    Ordering::Relaxed,
                ) {
                    Ok(_) => {
```

--------------------------------

### Starting a Receive Operation

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/array.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Attempts to reserve a slot for receiving a message by updating the head pointer.

```rust
/// Attempts to reserve a slot for receiving a message.
    fn start_recv(&self, token: &mut Token) -> bool {
        let backoff = Backoff::new();
        let mut head = self.head.load(Ordering::Relaxed);

        loop {
            // Deconstruct the head.
            let index = head & (self.mark_bit - 1);
            let lap = head & !(self.one_lap - 1);

            // Inspect the corresponding slot.
            debug_assert!(index < self.buffer.len());
            let slot = unsafe { self.buffer.get_unchecked(index) };
            let stamp = slot.stamp.load(Ordering::Acquire);

            // If the stamp is ahead of the head by 1, we may attempt to pop.
            if head + 1 == stamp {
                let new = if index + 1 < self.cap {
                    // Same lap, incremented index.
                    // Set to `{ lap: lap, mark: 0, index: index + 1 }`.
                    head + 1
                } else {
                    // One lap forward, index wraps around to zero.
                    // Set to `{ lap: lap.wrapping_add(1), mark: 0, index: 0 }`.
                    lap.wrapping_add(self.one_lap)
                };

                // Try moving the head.
                match self.head.compare_exchange_weak(
                    head,
                    new,
                    Ordering::SeqCst,
                    Ordering::Relaxed,
                ) {
                    Ok(_) => {
```

--------------------------------

### Start receive operation

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/list.rs.html?search=

Attempts to reserve a slot for receiving a message from the channel. It handles block transitions and empty channel states.

```rust
fn start_recv(&self, token: &mut Token) -> bool {
        let backoff = Backoff::new();
        let mut head = self.head.index.load(Ordering::Acquire);
        let mut block = self.head.block.load(Ordering::Acquire);

        loop {
            // Calculate the offset of the index into the block.
            let offset = (head >> SHIFT) % LAP;

            // If we reached the end of the block, wait until the next one is installed.
            if offset == BLOCK_CAP {
                backoff.snooze();
                head = self.head.index.load(Ordering::Acquire);
                block = self.head.block.load(Ordering::Acquire);
                continue;
            }

            let mut new_head = head + (1 << SHIFT);

            if new_head & MARK_BIT == 0 {
                atomic::fence(Ordering::SeqCst);
                let tail = self.tail.index.load(Ordering::Relaxed);

                // If the tail equals the head, that means the channel is empty.
                if head >> SHIFT == tail >> SHIFT {
                    // If the channel is disconnected...
                    if tail & MARK_BIT != 0 {
                        // ...then receive an error.
                        token.list.block = ptr::null();
                        return true;
                    } else {
                        // Otherwise, the receive operation is not ready.
                        return false;
                    }
                }

                // If head and tail are not in the same block, set `MARK_BIT` in head.
                if (head >> SHIFT) / LAP != (tail >> SHIFT) / LAP {
                    new_head |= MARK_BIT;
                }
            }

            // The block can be null here only if the first message is being sent into the channel.
            // In that case, just wait until it gets initialized.
            if block.is_null() {
                backoff.snooze();
                head = self.head.index.load(Ordering::Acquire);
                block = self.head.block.load(Ordering::Acquire);
                continue;
            }

            // Try moving the head index forward.
            match self.head.index.compare_exchange_weak(
                head,
                new_head,
                Ordering::SeqCst,
                Ordering::Acquire,
            ) {
                Ok(_) => unsafe {
                    // If we've reached the end of the block, move to the next one.
                    if offset + 1 == BLOCK_CAP {
                        let next = (*block).wait_next();
                        let mut next_index = (new_head & !MARK_BIT).wrapping_add(1 << SHIFT);
                        if !(*next).next.load(Ordering::Relaxed).is_null() {
                            next_index |= MARK_BIT;
                        }

                        self.head.block.store(next, Ordering::Release);
                        self.head.index.store(next_index, Ordering::Release);
                    }

                    token.list.block = block as *const u8;
                    token.list.offset = offset;
                    return true;
                },
                Err(h) => {
                    head = h;
                }
            }
        }
    }
```

--------------------------------

### fn at(when: Instant) -> Receiver<Instant>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.at.html

Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with a capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel at the moment in time 'when'.

```APIDOC
## Function: at

### Description
Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with a capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel at the moment in time `when`. If `when` is in the past, the message will be delivered instantly.

### Signature
`pub fn at(when: Instant) -> Receiver<Instant>`

### Parameters
- **when** (Instant) - The specific point in time at which the message should be delivered.

### Returns
- **Receiver<Instant>** - A receiver that will receive the `when` instant once the time has elapsed.
```

--------------------------------

### fn at(when: Instant) -> Receiver<Instant>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.at.html?search=std%3A%3Avec

Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with a capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel at the moment in time 'when'.

```APIDOC
## Function: at(when: Instant) -> Receiver<Instant>

### Description
Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with a capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel at the moment in time `when`. If `when` is in the past, the message will be delivered instantly to the receiver.

### Parameters
- **when** (Instant) - Required - The instant in time at which the message should be delivered.

### Returns
- **Receiver<Instant>** - A receiver that will receive the instant at which the message was sent.
```

--------------------------------

### pub fn at(when: Instant) -> Receiver<Instant>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.at.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with a capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel at the moment in time 'when'.

```APIDOC
## Function: at(when: Instant) -> Receiver<Instant>

### Description
Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with a capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel at the moment in time `when`.

### Parameters
- **when** (Instant) - The specific point in time at which the message should be delivered.

### Returns
- **Receiver<Instant>** - A receiver that will receive the `Instant` value once the specified time is reached.

### Example
```rust
use std::time::{Duration, Instant};
use crossbeam_channel::at;

let start = Instant::now();
let end = start + Duration::from_millis(100);

let r = at(end);

// This message will be received at the 'end' instant
assert_eq!(r.recv().unwrap(), end);
```
```

--------------------------------

### fn at

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.at.html?search=

Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with a capacity of 1 and never gets disconnected.

```APIDOC
## fn at(when: Instant) -> Receiver<Instant>

### Description
Creates a receiver that delivers a message at a certain instant in time. Exactly one message will be sent into the channel at the moment in time `when`.

### Parameters
- **when** (Instant) - The specific point in time at which the message should be delivered.

### Returns
- **Receiver<Instant>** - A receiver that will receive the `when` instant once the time is reached.

### Example
```rust
use std::time::{Instant, Duration};
use crossbeam_channel::at;

let deadline = Instant::now() + Duration::from_millis(500);
let r = at(deadline);

// The message is received at the deadline
assert_eq!(r.recv().unwrap(), deadline);
```
```

--------------------------------

### Ready-based receive from multiple channels

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Select.html

Demonstrates using the ready method to poll for available operations.

```rust
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);
    }
}
```

--------------------------------

### Get channel capacity

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/array.rs.html?search=

Returns the fixed capacity of the channel.

```rust
pub(crate) fn capacity(&self) -> Option<usize> {
        Some(self.cap)
    }
```

--------------------------------

### Implement Channel creation and handles

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/array.rs.html?search=

Methods for initializing a bounded channel and obtaining sender/receiver handles.

```rust
impl<T> Channel<T> {
    /// Creates a bounded channel of capacity `cap`.
    pub(crate) fn with_capacity(cap: usize) -> Self {
        assert!(cap > 0, "capacity must be positive");

        // Compute constants `mark_bit` and `one_lap`.
        let mark_bit = (cap + 1).next_power_of_two();
        let one_lap = mark_bit * 2;

        // Head is initialized to `{ lap: 0, mark: 0, index: 0 }`.
        let head = 0;
        // Tail is initialized to `{ lap: 0, mark: 0, index: 0 }`.
        let tail = 0;

        // Allocate a buffer of `cap` slots initialized
        // with stamps.
        let buffer: Box<[Slot<T>]> = (0..cap)
            .map(|i| {
                // Set the stamp to `{ lap: 0, mark: 0, index: i }`.
                Slot {
                    stamp: AtomicUsize::new(i),
                    msg: UnsafeCell::new(MaybeUninit::uninit()),
                }
            })
            .collect();

        Channel {
            buffer,
            cap,
            one_lap,
            mark_bit,
            head: CachePadded::new(AtomicUsize::new(head)),
            tail: CachePadded::new(AtomicUsize::new(tail)),
            senders: SyncWaker::new(),
            receivers: SyncWaker::new(),
        }
    }

    /// Returns a receiver handle to the channel.
    pub(crate) fn receiver(&self) -> Receiver<'_, T> {
        Receiver(self)
    }

    /// Returns a sender handle to the channel.
    pub(crate) fn sender(&self) -> Sender<'_, T> {
        Sender(self)
    }

    /// Attempts to reserve a slot for sending a message.
    fn start_send(&self, token: &mut Token) -> bool {
        let backoff = Backoff::new();
        let mut tail = self.tail.load(Ordering::Relaxed);

        loop {

```

--------------------------------

### Get channel capacity

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/list.rs.html?search=

Returns the capacity of the channel, which is currently None for this implementation.

```rust
pub(crate) fn capacity(&self) -> Option<usize> {
        None
    }
```

--------------------------------

### Get channel length

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Sender.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the current number of messages stored in the channel.

```rust
use crossbeam_channel::unbounded;

let (s, r) = unbounded();
assert_eq!(s.len(), 0);

s.send(1).unwrap();
s.send(2).unwrap();
assert_eq!(s.len(), 2);
```

--------------------------------

### pub fn ready(&mut self) -> usize

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Select.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Blocks until one of the operations becomes ready and returns its index.

```APIDOC
## pub fn ready(&mut self) -> usize

### Description
Blocks until one of the operations becomes ready. Once ready, the index of the operation is returned. Panics if no operations have been added to the Select instance.
```

--------------------------------

### Get channel capacity

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Receiver.html?search=

Returns the capacity of a bounded channel, or None for unbounded channels.

```rust
use crossbeam_channel::{bounded, unbounded};

let (_, r) = unbounded::<i32>();
assert_eq!(r.capacity(), None);

let (_, r) = bounded::<i32>(5);
assert_eq!(r.capacity(), Some(5));

let (_, r) = bounded::<i32>(0);
assert_eq!(r.capacity(), Some(0));
```

--------------------------------

### Get number of messages in channel

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Receiver.html?search=

Returns the current count of messages waiting in the channel.

```rust
use crossbeam_channel::unbounded;

let (s, r) = unbounded();
assert_eq!(r.len(), 0);

s.send(1).unwrap();
s.send(2).unwrap();
assert_eq!(r.len(), 2);
```

--------------------------------

### Implement Channel methods

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/list.rs.html

Core methods for initializing the channel and managing sender/receiver handles.

```rust
impl<T> Channel<T> {
    /// Creates a new unbounded channel.
    pub(crate) fn new() -> Self {
        Channel {
            head: CachePadded::new(Position {
                block: AtomicPtr::new(ptr::null_mut()),
                index: AtomicUsize::new(0),
            }),
            tail: CachePadded::new(Position {
                block: AtomicPtr::new(ptr::null_mut()),
                index: AtomicUsize::new(0),
            }),
            receivers: SyncWaker::new(),
            _marker: PhantomData,
        }
    }

    /// Returns a receiver handle to the channel.
    pub(crate) fn receiver(&self) -> Receiver<'_, T> {
        Receiver(self)
    }

    /// Returns a sender handle to the channel.
    pub(crate) fn sender(&self) -> Sender<'_, T> {
        Sender(self)
    }
```

--------------------------------

### Implement start_send logic

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/list.rs.html

Attempts to reserve a slot for sending a message, handling block allocation and tail advancement.

```rust
    /// Attempts to reserve a slot for sending a message.
    fn start_send(&self, token: &mut Token) -> bool {
        let backoff = Backoff::new();
        let mut tail = self.tail.index.load(Ordering::Acquire);
        let mut block = self.tail.block.load(Ordering::Acquire);
        let mut next_block = None;

        loop {
            // Check if the channel is disconnected.
            if tail & MARK_BIT != 0 {
                token.list.block = ptr::null();
                return true;
            }

            // Calculate the offset of the index into the block.
            let offset = (tail >> SHIFT) % LAP;

            // If we reached the end of the block, wait until the next one is installed.
            if offset == BLOCK_CAP {
                backoff.snooze();
                tail = self.tail.index.load(Ordering::Acquire);
                block = self.tail.block.load(Ordering::Acquire);
                continue;
            }

            // If we're going to have to install the next block, allocate it in advance in order to
            // make the wait for other threads as short as possible.
            if offset + 1 == BLOCK_CAP && next_block.is_none() {
                next_block = Some(Block::<T>::new());
            }

            // If this is the first message to be sent into the channel, we need to allocate the
            // first block and install it.
            if block.is_null() {
                let new = Box::into_raw(Block::<T>::new());

                if self
                    .tail
                    .block
                    .compare_exchange(block, new, Ordering::Release, Ordering::Relaxed)
                    .is_ok()
                {
                    self.head.block.store(new, Ordering::Release);
                    block = new;
                } else {
                    next_block = unsafe { Some(Box::from_raw(new)) };
                    tail = self.tail.index.load(Ordering::Acquire);
                    block = self.tail.block.load(Ordering::Acquire);
                    continue;
                }
            }

            let new_tail = tail + (1 << SHIFT);

            // Try advancing the tail forward.
            match self.tail.index.compare_exchange_weak(
                tail,
                new_tail,
                Ordering::SeqCst,
                Ordering::Acquire,
            ) {
                Ok(_) => unsafe {
                    // If we've reached the end of the block, install the next one.
```

--------------------------------

### Create a new Select instance

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Select.html

Initializes an empty list of channel operations.

```rust
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());
```

--------------------------------

### Create a bounded channel with capacity 1

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.bounded.html

Demonstrates sending messages through a channel with a capacity of 1, showing how the sender blocks when the buffer is full.

```rust
use std::thread;
use std::time::Duration;
use crossbeam_channel::bounded;

let (s, r) = bounded(1);

// This call returns immediately because there is enough space in the channel.
s.send(1).unwrap();

thread::spawn(move || {
    // This call blocks the current thread because the channel is full.
    // It will be able to complete only after the first message is received.
    s.send(2).unwrap();
});

thread::sleep(Duration::from_secs(1));
assert_eq!(r.recv(), Ok(1));
assert_eq!(r.recv(), Ok(2));
```

--------------------------------

### take

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.IntoIter.html?search=u32+-%3E+bool

Creates an iterator that yields the first n elements.

```APIDOC
fn take(self, n: usize) -> Take<Self>
```

--------------------------------

### Select::new

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Select.html

Creates an empty list of channel operations for selection.

```APIDOC
## Select::new()

### Description
Creates an empty list of channel operations for selection.
```

--------------------------------

### never<T>()

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.never.html?search=std%3A%3Avec

Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

```APIDOC
## fn never<T>() -> Receiver<T>

### Description
Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

### Signature
`pub const fn never<T>() -> Receiver<T>`

### Usage
This function is typically used in scenarios like `select!` macros where a channel is required but no message should ever be received, such as providing a default case or a placeholder for an optional timeout.
```

--------------------------------

### pub fn ready(&mut self) -> usize

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Select.html?search=u32+-%3E+bool

Blocks the current thread until one of the operations becomes ready, then returns its index.

```APIDOC
## pub fn ready(&mut self) -> usize

### Description
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.

### Panics
Panics if no operations have been added to Select.
```

--------------------------------

### never<T>() -> Receiver<T>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.never.html?search=u32+-%3E+bool

Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

```APIDOC
## Function: never<T>()

### Description
Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

### Signature
`pub const fn never<T>() -> Receiver<T>`

### Usage
This function is typically used in `select!` blocks to provide a channel that will never receive a message, effectively disabling a branch when a timeout or other condition is not applicable.

### Example
```rust
use crossbeam_channel::{after, select, never, unbounded};

let (s, r) = unbounded();
let duration = None;

// Create a channel that times out or never receives if duration is None
let timeout = duration
    .map(|d| after(d))
    .unwrap_or(never());

select! {
    recv(r) -> msg => println!("Received: {:?}", msg),
    recv(timeout) -> _ => println!("timed out or never"),
}
```
```

--------------------------------

### never<T>() -> Receiver<T>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.never.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

```APIDOC
## Function: never<T>()

### Description
Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

### Signature
`pub const fn never<T>() -> Receiver<T>`

### Usage
This function is typically used in `select!` blocks to provide a channel that will never trigger a receive operation, often as a fallback when an optional timeout or event is not provided.
```

--------------------------------

### Initialize Selection Handles

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/select_macro.rs.html

Macro rule to create the list of handles and add operations for the select! block.

```rust
(@init
    ($($cases:tt)*)
    $default:tt
) => {{
    const _LEN: usize = $crate::crossbeam_channel_internal!(@count ($($cases)*));
    let _handle: &dyn $crate::internal::SelectHandle = &$crate::never::<()>();

    #[allow(unused_mut, clippy::zero_repeat_side_effects)]
    let mut _sel = [(_handle, 0, ::std::ptr::null()); _LEN];

    $crate::crossbeam_channel_internal!(
        @add
        _sel
        ($($cases)*)
        $default
        (
            (0usize _oper0)
            (1usize _oper1)
            (2usize _oper2)
            (3usize _oper3)
            (4usize _oper4)
            (5usize _oper5)
            (6usize _oper6)
            (7usize _oper7)
            (8usize _oper8)
            (9usize _oper9)
            (10usize _oper10)
            (11usize _oper11)
            (12usize _oper12)
            (13usize _oper13)
            (14usize _oper14)
            (15usize _oper15)
            (16usize _oper16)
            (17usize _oper17)
            (18usize _oper18)
            (19usize _oper19)
            (20usize _oper20)
            (21usize _oper21)
            (22usize _oper22)
            (23usize _oper23)
            (24usize _oper24)
            (25usize _oper25)
            (26usize _oper26)
            (27usize _oper27)
            (28usize _oper28)
            (29usize _oper29)
            (30usize _oper30)
            (31usize _oper31)
        )
        ()
    )
}};
```

--------------------------------

### Select Initialization and Counting

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/select_macro.rs.html?search=std%3A%3Avec

Internal macros for counting select cases and initializing the selection handle array.

```rust
// Create the list of handles and add operations to it.
    (@init
        ($($cases:tt)*)
        $default:tt
    ) => {{
        const _LEN: usize = $crate::crossbeam_channel_internal!(@count ($($cases)*));
        let _handle: &dyn $crate::internal::SelectHandle = &$crate::never::<()>();

        #[allow(unused_mut, clippy::zero_repeat_side_effects)]
        let mut _sel = [(_handle, 0, ::std::ptr::null()); _LEN];

        $crate::crossbeam_channel_internal!(
            @add
            _sel
            ($($cases)*)
            $default
            (
                (0usize _oper0)
                (1usize _oper1)
                (2usize _oper2)
                (3usize _oper3)
                (4usize _oper4)
                (5usize _oper5)
                (6usize _oper6)
                (7usize _oper7)
                (8usize _oper8)
                (9usize _oper9)
                (10usize _oper10)
                (11usize _oper11)
                (12usize _oper12)
                (13usize _oper13)
                (14usize _oper14)
                (15usize _oper15)
                (16usize _oper16)
                (17usize _oper17)
                (18usize _oper18)
                (19usize _oper19)
                (20usize _oper20)
                (21usize _oper21)
                (22usize _oper22)
                (23usize _oper23)
                (24usize _oper24)
                (25usize _oper25)
                (26usize _oper26)
                (27usize _oper27)
                (28usize _oper28)
                (29usize _oper29)
                (30usize _oper30)
                (31usize _oper31)
            )
            ()
        )
    }};
```

```rust
// Count the listed cases.
    (@count ()) => {
        0
    };
    (@count ($oper:ident $args:tt -> $res:pat => $body:tt, $($cases:tt)*)) => {
        1 + $crate::crossbeam_channel_internal!(@count ($($cases)*))
    };
```

```rust
// Run blocking selection.
    (@add
        $sel:ident
        ()
        ()
        $labels:tt
        $cases:tt
    ) => {{
        let _oper: $crate::SelectedOperation<'_> = {
            let _oper = $crate::internal::select(&mut $sel, _IS_BIASED);
```

--------------------------------

### never<T>() -> Receiver<T>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.never.html?search=

Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

```APIDOC
## Function: never<T>()

### Description
Creates a receiver that never delivers messages. The channel is bounded with capacity of 0 and never gets disconnected.

### Signature
`pub const fn never<T>() -> Receiver<T>`

### Usage
This function is typically used in `select!` blocks to provide a channel that will never receive a message, effectively disabling a branch when a timeout or other condition is not required.
```

--------------------------------

### Initialize Bounded Channel

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/array.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new bounded channel with a specified capacity, preallocating the required slots.

```rust
impl<T> Channel<T> {
    /// Creates a bounded channel of capacity `cap`.
    pub(crate) fn with_capacity(cap: usize) -> Self {
        assert!(cap > 0, "capacity must be positive");

        // Compute constants `mark_bit` and `one_lap`.
        let mark_bit = (cap + 1).next_power_of_two();
        let one_lap = mark_bit * 2;

        // Head is initialized to `{ lap: 0, mark: 0, index: 0 }`.
        let head = 0;
        // Tail is initialized to `{ lap: 0, mark: 0, index: 0 }`.
        let tail = 0;

        // Allocate a buffer of `cap` slots initialized
        // with stamps.
        let buffer: Box<[Slot<T>]> = (0..cap)
            .map(|i| {
                // Set the stamp to `{ lap: 0, mark: 0, index: i }`.
                Slot {
                    stamp: AtomicUsize::new(i),
                    msg: UnsafeCell::new(MaybeUninit::uninit()),
                }
            })
            .collect();

        Channel {
            buffer,
            cap,
            one_lap,
            mark_bit,
            head: CachePadded::new(AtomicUsize::new(head)),
            tail: CachePadded::new(AtomicUsize::new(tail)),
            senders: SyncWaker::new(),
            receivers: SyncWaker::new(),
        }
    }
```

--------------------------------

### never<T>() -> Receiver<T>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.never.html

Creates a receiver that never delivers messages. The channel is bounded with a capacity of 0 and never gets disconnected.

```APIDOC
## fn never<T>() -> Receiver<T>

### Description
Creates a receiver that never delivers messages. The channel is bounded with a capacity of 0 and never gets disconnected.

### Returns
- **Receiver<T>** - A receiver that will never receive any messages.
```

--------------------------------

### fn at

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.at.html?search=u32+-%3E+bool

Creates a receiver that delivers a message at a certain instant in time. The channel is bounded with capacity of 1 and never gets disconnected.

```APIDOC
## fn at(when: Instant) -> Receiver<Instant>

### Description
Creates a receiver that delivers a message at a certain instant in time. Exactly one message will be sent into the channel at the moment in time `when`. If `when` is in the past, the message will be delivered instantly.

### Parameters
- **when** (Instant) - Required - The instant in time at which the message should be delivered.

### Returns
- **Receiver<Instant>** - A receiver that will receive the instant at which the message was sent.
```

--------------------------------

### Using select! with a default timeout

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/select_macro.rs.html?search=

Demonstrates using the default case in a select! block to handle timeouts when no channel operations are ready.

```rust
select! {
    recv(r1) -> msg => panic!(),
    recv(r2) -> msg => panic!(),
    default(Duration::from_millis(100)) => println!("timed out"),
}
```

--------------------------------

### Create a bounded channel

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.bounded.html?search=

Shows the function signature for creating a channel with a specific capacity.

```rust
pub fn bounded<T>(cap: usize) -> (Sender<T>, Receiver<T>)
```

--------------------------------

### select()

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Select.html

Blocks until one of the operations becomes ready and selects it. If multiple operations are ready, a random one is selected.

```APIDOC
## pub fn select(&mut self) -> SelectedOperation<'a>

### Description
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.

### Notes
- Panics if no operations have been added to Select.
- The selected operation must be completed with SelectedOperation::send or SelectedOperation::recv.
```

--------------------------------

### tick(duration: Duration) -> Receiver<Instant>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.tick.html?search=u32+-%3E+bool

Creates a receiver that delivers messages periodically. The channel is bounded with a capacity of 1 and never gets disconnected. Each message sent is the Instant at which it was sent.

```APIDOC
## Function: tick

### Signature
`pub fn tick(duration: Duration) -> Receiver<Instant>`

### Description
Creates a receiver that delivers messages periodically. The channel is bounded with a capacity of 1 and never gets disconnected. Messages are sent into the channel in intervals of `duration`.

### Parameters
- **duration** (std::time::Duration) - The interval at which messages are sent into the channel.

### Returns
- **Receiver<Instant>** - A receiver that yields the `Instant` at which each message was sent.

### Example
```rust
use std::time::{Duration, Instant};
use crossbeam_channel::tick;

let start = Instant::now();
let ticker = tick(Duration::from_millis(100));

for _ in 0..5 {
    ticker.recv().unwrap();
    println!("elapsed: {:?}", start.elapsed());
}
```
```

--------------------------------

### Channel state and capacity methods

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/flavors/array.rs.html

Methods to query the current length, capacity, and connection status of the channel.

```rust
pub(crate) fn len(&self) -> usize {
        loop {
            // Load the tail, then load the head.
            let tail = self.tail.load(Ordering::SeqCst);
            let head = self.head.load(Ordering::SeqCst);

            // If the tail didn't change, we've got consistent values to work with.
            if self.tail.load(Ordering::SeqCst) == tail {
                let hix = head & (self.mark_bit - 1);
                let tix = tail & (self.mark_bit - 1);

                return if hix < tix {
                    tix - hix
                } else if hix > tix {
                    self.cap - hix + tix
                } else if (tail & !self.mark_bit) == head {
                    0
                } else {
                    self.cap
                };
            }
        }
    }
```

```rust
pub(crate) fn capacity(&self) -> Option<usize> {
        Some(self.cap)
    }
```

```rust
pub(crate) fn disconnect(&self) -> bool {
        let tail = self.tail.fetch_or(self.mark_bit, Ordering::SeqCst);

        if tail & self.mark_bit == 0 {
            self.senders.disconnect();
            self.receivers.disconnect();
            true
        } else {
            false
        }
    }
```

```rust
pub(crate) fn is_disconnected(&self) -> bool {
        self.tail.load(Ordering::SeqCst) & self.mark_bit != 0
    }
```

```rust
pub(crate) fn is_empty(&self) -> bool {
        let head = self.head.load(Ordering::SeqCst);
        let tail = self.tail.load(Ordering::SeqCst);

        // Is the tail equal to the head?
        //
        // Note: If the head changes just before we load the tail, that means there was a moment
        // when the channel was not empty, so it is safe to just return `false`.
        (tail & !self.mark_bit) == head
    }
```

```rust
pub(crate) fn is_full(&self) -> bool {
        let tail = self.tail.load(Ordering::SeqCst);
        let head = self.head.load(Ordering::SeqCst);

        // Is the head lagging one lap behind tail?
        //
        // Note: If the tail changes just before we load the head, that means there was a moment
        // when the channel was not full, so it is safe to just return `false`.
        head.wrapping_add(self.one_lap) == tail & !self.mark_bit
    }
```

--------------------------------

### Basic Channel Usage

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/index.html?search=

Demonstrates creating an unbounded channel and performing basic send and receive operations.

```rust
use crossbeam_channel::unbounded;

// Create a channel of unbounded capacity.
let (s, r) = unbounded();

// Send a message into the channel.
s.send("Hello, world!").unwrap();

// Receive the message from the channel.
assert_eq!(r.recv(), Ok("Hello, world!"));
```

--------------------------------

### tick(duration: Duration) -> Receiver<Instant>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.tick.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a receiver that delivers messages periodically. The channel is bounded with a capacity of 1 and never gets disconnected. Messages are sent into the channel in intervals of duration, where each message is the Instant at which it is sent.

```APIDOC
## Function: tick

### Description
Creates a receiver that delivers messages periodically. The channel is bounded with a capacity of 1 and never gets disconnected. Messages will be sent into the channel in intervals of `duration`.

### Signature
`pub fn tick(duration: Duration) -> Receiver<Instant>`

### Parameters
- **duration** (Duration) - The interval at which messages are sent.

### Returns
- **Receiver<Instant>** - A receiver that yields the Instant at which each message was sent.

### Example
```rust
use std::time::{Duration, Instant};
use crossbeam_channel::tick;

let start = Instant::now();
let ticker = tick(Duration::from_millis(100));

for _ in 0..5 {
    ticker.recv().unwrap();
    println!("elapsed: {:?}", start.elapsed());
}
```
```

--------------------------------

### Use select! with a timeout

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/select_macro.rs.html

Demonstrates using the default case in select! to handle timeouts when no operations are ready.

```rust
thread::spawn(move || {
    thread::sleep(Duration::from_millis(500));
    s2.send(20).unwrap();
});

// None of the two operations will become ready within 100 milliseconds.
select! {
    recv(r1) -> msg => panic!(),
    recv(r2) -> msg => panic!(),
    default(Duration::from_millis(100)) => println!("timed out"),
}
```

--------------------------------

### Create an unbounded channel

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.unbounded.html

Demonstrates initializing an unbounded channel and using it to send the result of a computation from a spawned thread.

```rust
use std::thread;
use crossbeam_channel::unbounded;

let (s, r) = unbounded();

// Computes the n-th Fibonacci number.
fn fib(n: i32) -> i32 {
    if n <= 1 {
        n
    } else {
        fib(n - 1) + fib(n - 2)
    }
}

// Spawn an asynchronous computation.
thread::spawn(move || s.send(fib(20)).unwrap());

// Print the result of the computation.
println!("{}", r.recv().unwrap());
```

--------------------------------

### pub fn after(duration: Duration) -> Receiver<Instant>

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/fn.after.html

Creates a receiver that delivers a message after a certain duration of time. The channel is bounded with capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel after the duration elapses.

```APIDOC
## Function: after

### Signature
`pub fn after(duration: Duration) -> Receiver<Instant>`

### Description
Creates a receiver that delivers a message after a certain duration of time. The channel is bounded with capacity of 1 and never gets disconnected. Exactly one message will be sent into the channel after `duration` elapses. The message is the instant at which it is sent.

### Parameters
- **duration** (std::time::Duration) - The amount of time to wait before sending the message.

### Returns
- **Receiver<Instant>** - A receiver that will receive the instant at which the message was sent.
```

--------------------------------

### select()

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/select.rs.html?search=u32+-%3E+bool

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

```APIDOC
## pub fn select(&mut self) -> SelectedOperation<'a>

### Description
Blocks until one of the operations becomes ready and selects it. If multiple operations are ready, one is chosen.

### Returns
- **SelectedOperation<'a>** - The operation that was selected.
```

--------------------------------

### select()

Source: https://docs.rs/crossbeam-channel/latest/src/crossbeam_channel/select.rs.html?search=std%3A%3Avec

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

```APIDOC
## fn select(&mut self) -> SelectedOperation<'a>

### Description
Blocks until one of the operations becomes ready and selects it. If multiple operations are ready, one is selected randomly.

### Returns
- **SelectedOperation<'a>** - The operation that was selected.
```

--------------------------------

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

Source: https://docs.rs/crossbeam-channel/latest/crossbeam_channel/struct.Select.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Attempts to find a ready operation without blocking. Returns the index of a ready operation or an error if none are ready.

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

### Description
Attempts to find a ready operation without blocking. If an operation is ready, its index is returned. If multiple operations are ready, a random one is chosen. If none are ready, an error is returned.
```
Tokens:
Raw