Struct st3::fifo::Worker

source ·

pub struct Worker<T> { /* private fields */ }

Expand description

Handle for single-threaded FIFO push and pop operations.

Implementations§

source §

impl<T> Worker<T>

source

pub fn new(min_capacity: usize) -> Self

Creates a new queue and returns a Worker handle.

The capacity of a queue is always a power of two. It is set to the smallest power of two greater than or equal to the requested minimum capacity.

Panic

This method will panic if the minimum requested capacity is greater than 2³¹ on targets that support 64-bit atomics, or greater than 2¹⁵ on targets that only support 32-bit atomics.

source

pub fn stealer(&self) -> Stealer<T>

Creates a new Stealer handle associated to this Worker.

An arbitrary number of Stealer handles can be created, either using this method or cloning an existing Stealer handle.

source

pub fn stealer_ref(&self) -> &Stealer<T>

Creates a reference to a Stealer handle associated to this Worker.

This is a zero-cost reference-to-reference conversion: the reference count to the underlying queue is not modified. The returned reference can in particular be used to perform a cheap equality check with another Stealer and verify that it is associated to the same Worker.

source

pub fn capacity(&self) -> usize

Returns the capacity of the queue.

source

pub fn spare_capacity(&self) -> usize

Returns the number of items that can be successfully pushed onto the queue.

Note that that the spare capacity may be underestimated due to concurrent stealing operations.

source

pub fn is_empty(&self) -> bool

Returns true if the queue is empty.

Note that the queue size is somewhat ill-defined in a multi-threaded context, but it is warranted that if is_empty() returns true, a subsequent call to pop() will fail.

source

pub fn push(&self, item: T) -> Result<(), T>

Attempts to push one item at the tail of the queue.

Errors

This will fail if the queue is full, in which case the item is returned as the error field.

source

pub fn extend<I: IntoIterator<Item = T>>(&self, iter: I)

Attempts to push the content of an iterator at the tail of the queue.

It is the responsibility of the caller to ensure that there is enough spare capacity to accommodate all iterator items, for instance by calling spare_capacity beforehand. Otherwise, the iterator is dropped while still holding the items in excess.

source

pub fn pop(&self) -> Option<T>

Attempts to pop one item from the head of the queue.

This returns None if the queue is empty.

source

pub fn drain<C>(&self, count_fn: C) -> Result<Drain<'_, T>, StealError>where
C: FnMut(usize) -> usize,

Returns an iterator that steals items from the head of the queue.

The returned iterator steals up to N items, where N is specified by a closure which takes as argument the total count of items available for stealing. Upon success, the number of items ultimately stolen can be from 1 to N, depending on the number of available items.