Struct crossbeam_deque::Deque

pub struct Deque<T> { /* fields omitted */ }

A concurrent work-stealing deque.

A deque has two ends: bottom and top. Elements can be pushed into the bottom and popped from the bottom. The top end is special in that elements can only be stolen from it using the steal method.

Stealers

While Deque doesn't implement Sync, it can create Stealers using the method stealer, and those can be easily shared among multiple threads. Stealers can only steal elements from the top end of the deque.

Capacity

The data structure is dynamically grows as elements are inserted and removed from it. If the internal buffer gets full, a new one twice the size of the original is allocated. Similarly, if it is less than a quarter full, a new buffer half the size of the original is allocated.

In order to prevent frequent resizing (reallocations may be costly), it is possible to specify a large minimum capacity for the deque by calling Deque::with_min_capacity. This constructor will make sure that the internal buffer never shrinks below that size.

Examples

use crossbeam_deque::{Deque, Steal};

let d = Deque::with_min_capacity(1000);
let s = d.stealer();

d.push('a');
d.push('b');
d.push('c');

assert_eq!(d.pop(), Some('c'));
assert_eq!(d.steal(), Steal::Data('a'));
assert_eq!(s.steal(), Steal::Data('b'));

Methods

impl<T> Deque<T>

pub fn new() -> Deque<T>

Returns a new deque.

The internal buffer is destructed as soon as the deque and all its stealers get dropped.

Examples

use crossbeam_deque::Deque;

let d = Deque::<i32>::new();

pub fn with_min_capacity(min_cap: usize) -> Deque<T>

Returns a new deque with the specified minimum capacity.

If the capacity is not a power of two, it will be rounded up to the next one.

Examples

use crossbeam_deque::Deque;

// The minimum capacity will be rounded up to 1024.
let d = Deque::<i32>::with_min_capacity(1000);
assert_eq!(d.min_capacity(), 1024);
assert_eq!(d.capacity(), 1024);

pub fn is_empty(&self) -> bool

Returns true if the deque is empty.

Examples

use crossbeam_deque::Deque;

let d = Deque::new();
assert!(d.is_empty());
d.push("foo");
assert!(!d.is_empty());

pub fn len(&self) -> usize

Returns the number of elements in the deque.

Examples

use crossbeam_deque::Deque;

let d = Deque::new();
d.push('a');
d.push('b');
d.push('c');
assert_eq!(d.len(), 3);

pub fn min_capacity(&self) -> usize

Returns the minimum capacity of the deque.

The minimum capacity can be specified in Deque::with_min_capacity.

Examples

use crossbeam_deque::Deque;

// Gets rounded to the next power of two.
let d = Deque::<i32>::with_min_capacity(50);
assert_eq!(d.min_capacity(), 64);
assert_eq!(d.capacity(), 64);

pub fn capacity(&self) -> usize

Returns the number of elements the deque can hold without reallocating.

Examples

use crossbeam_deque::Deque;

let d = Deque::with_min_capacity(50);
assert_eq!(d.capacity(), 64);

for i in 0..200 {
    d.push(i);
}
assert_eq!(d.capacity(), 256);

pub fn shrink_to_fit(&self)

Shrinks the capacity of the deque as much as possible.

The capacity will drop down as close as possible to the length but there may still be some free space left.

Examples

use crossbeam_deque::Deque;

// Insert a lot of elements. This makes the buffer grow.
let d = Deque::new();
for i in 0..200 {
    d.push(i);
}

// Remove all elements.
let s = d.stealer();
for i in 0..200 {
    s.steal();
}

// Stealers cannot shrink the buffer, so the capacity is still very large.
assert!(d.capacity() >= 200);

// Shrink the buffer. The capacity drops down, but some free space may still be left.
d.shrink_to_fit();
assert!(d.capacity() < 50);

pub fn push(&self, value: T)

Pushes an element into the bottom of the deque.

If the internal buffer is full, a new one twice the capacity of the current one will be allocated.

Examples

use crossbeam_deque::Deque;

let d = Deque::new();
d.push(1);
d.push(2);

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

Pops an element from the bottom of the deque.

If the internal buffer is less than a quarter full, a new buffer half the capacity of the current one will be allocated.

Examples

use crossbeam_deque::Deque;

let d = Deque::new();
d.push(1);
d.push(2);

assert_eq!(d.pop(), Some(2));
assert_eq!(d.pop(), Some(1));
assert_eq!(d.pop(), None);

pub fn steal(&self) -> Steal<T>

Steals an element from the top of the deque.

Unlike most methods in concurrent data structures, if another operation gets in the way while attempting to steal data, this method will return immediately with Steal::Retry instead of retrying.

If the internal buffer is less than a quarter full, a new buffer half the capacity of the current one will be allocated.

Examples

use crossbeam_deque::{Deque, Steal};

let d = Deque::new();
d.push(1);
d.push(2);

// Attempt to steal an element.
//
// No other threads are working with the deque, so this time we know for sure that we
// won't get `Steal::Retry` as the result.
assert_eq!(d.steal(), Steal::Data(1));

// Attempt to steal an element, but keep retrying if we get `Retry`.
let stolen = loop {
    match d.steal() {
        Steal::Empty => break None,
        Steal::Data(data) => break Some(data),
        Steal::Retry => {}
    }
};
assert_eq!(stolen, Some(2));

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

Creates a stealer that can be shared with other threads.

Examples

use crossbeam_deque::{Deque, Steal};
use std::thread;

let d = Deque::new();
d.push(1);
d.push(2);

let s = d.stealer();

thread::spawn(move || {
    assert_eq!(s.steal(), Steal::Data(1));
}).join().unwrap();

Trait Implementations

impl<T: Send> Send for Deque<T>

impl<T> Debug for Deque<T>

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

Formats the value using the given formatter.

impl<T> Default for Deque<T>

fn default() -> Deque<T>

Returns the "default value" for a type.