Struct OwnedConsumer

pub struct OwnedConsumer<T: Linked<Links<T>>> { /* private fields */ }

An owned handle that holds the right to dequeue elements from the queue.

This can be used when one thread wishes to dequeue many elements at a time, to avoid the overhead of ensuring mutual exclusion on every dequeue or try_dequeue call.

This type is returned by the MpscQueue::consume_owned and MpscQueue::try_consume_owned methods.

This is similar to the Consumer type, but the queue is stored in an Arc rather than borrowed. This allows a single OwnedConsumer instance to be stored in a struct and used indefinitely.

Since the queue is stored in an Arc, this requires the alloc feature flag to be enabled.

Implementations

impl<T: Linked<Links<T>>> OwnedConsumer<T>

pub fn dequeue(&self) -> Option<T::Handle>

Dequeue an element from the queue.

As discussed in the algorithm description on 1024cores.net, it is possible for this queue design to enter an inconsistent state if the consumer tries to dequeue an element while a producer is in the middle of enqueueing a new element. If this occurs, the consumer must briefly wait before dequeueing an element. This method will wait by spinning with an exponential backoff if the queue is in an inconsistent state.

The Consumer::try_dequeue will return an error rather than waiting when the queue is in an inconsistent state.

Returns

• Some(T::Handle) if an element was successfully dequeued
• None if the queue is empty

pub fn try_dequeue(&self) -> Result<T::Handle, TryDequeueError>

Try to dequeue an element from the queue, without waiting if the queue is in an inconsistent state.

As discussed in the algorithm description on 1024cores.net, it is possible for this queue design to enter an inconsistent state if the consumer tries to dequeue an element while a producer is in the middle of enqueueing a new element. If this occurs, the consumer must briefly wait before dequeueing an element. This method returns TryDequeueError::Inconsistent when the queue is in an inconsistent state.

The Consumer::dequeue method will instead wait (by spinning with an exponential backoff) when the queue is in an inconsistent state.

Returns

• T::Handle if an element was successfully dequeued
• TryDequeueError::Empty if there are no elements in the queue
• TryDequeueError::Inconsistent if the queue is currently in an inconsistent state

Returns

• Some(T::Handle) if an element was successfully dequeued
• None if the queue is empty

pub fn has_producers(&self) -> bool

Returns true if any producers exist for this queue.

Trait Implementations

impl<T: Linked<Links<T>>> Debug for OwnedConsumer<T>

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

Formats the value using the given formatter.

impl<T: Linked<Links<T>>> Drop for OwnedConsumer<T>

fn drop(&mut self)

Executes the destructor for this type.