Struct voluntary_servitude::VoluntaryServitude

pub struct VoluntaryServitude<T>(_);

Appendable list with lock-free iterator (also called VS)

Examples

• Single-thread
• Multi-producer, multi-consumer

Single thread

let (a, b, c) = (0usize, 1usize, 2usize);
// VS alias to VoluntaryServitude
// vs! alias to voluntary_servitude! (and operate like vec!)
let list = vs![a, b, c];
assert_eq!(list.iter().collect::<Vec<_>>(), vec![&a, &b, &c]);

// Current VS's length
// Be careful with race conditions since the value, when used, may not be true anymore
assert_eq!(list.len(), 3);

// The 'iter' method makes a one-time lock-free iterator (Iter)
for (index, element) in list.iter().enumerate() {
    assert_eq!(index, *element);
}

// You can get the current iteration index
// iter.next() == iter.len() means iteration ended (iter.next() == None)
let mut iter = list.iter();
assert_eq!(iter.index(), 0);
assert_eq!(iter.next(), Some(&0));
assert_eq!(iter.index(), 1);

// List can also be cleared (but current iterators are not affected)
list.clear();

assert_eq!(iter.len(), 3);
assert_eq!(list.len(), 0);
assert_eq!(list.iter().len(), 0);
assert_eq!(list.iter().next(), None);

println!("Single thread example ended without errors");

Multi-producer, multi-consumer

#[macro_use]
extern crate voluntary_servitude;
use std::{sync::Arc, thread::spawn};

const CONSUMERS: usize = 8;
const PRODUCERS: usize = 4;
const ELEMENTS: usize = 10000000;

fn main() {
    let list = Arc::new(vs![]);
    let mut handlers = vec![];

    // Creates producer threads to insert 10k elements
    for _ in 0..PRODUCERS {
        let l = Arc::clone(&list);
        handlers.push(spawn(move || {
            let _ = (0..ELEMENTS).map(|i| l.append(i)).count();
        }));
    }

    // Creates consumer threads to print number of elements
    // Until all of them are inserted
    for _ in 0..CONSUMERS {
        const TOTAL: usize = PRODUCERS * ELEMENTS;
        let consumer = Arc::clone(&list);
        handlers.push(spawn(move || loop {
            let count = consumer.iter().count();
            println!("{} elements", count);
            if count >= TOTAL { break };
        }));
    }

    // Join threads
    for handler in handlers.into_iter() {
        handler.join().expect("Failed to join thread");
    }

    println!("Multi-thread rust example ended without errors");
}

Implementations

impl<T> VoluntaryServitude<T>

pub fn len(&self) -> usize

Returns current size, be careful with race conditions when using it

let list = vs![3, 2];
assert_eq!(list.len(), 2);
list.append(5);
assert_eq!(list.len(), 3);
list.clear();
assert_eq!(list.len(), 0);

pub fn is_empty(&self) -> bool

Checks if VS is currently empty, be careful with race conditions when using it

let list = vs![];
assert!(list.is_empty());
list.append(());
assert!(!list.is_empty());

pub fn append(&self, value: T)

Inserts element after last node

let list = vs![];
let mut iter = list.iter();
list.append(3);
assert!(iter.is_empty());
iter = list.iter();
list.append(8);
assert_eq!(iter.collect::<Vec<_>>(), vec![&3, &8]);

pub fn iter(&self) -> Iter<'_, T>

Makes lock-free iterator based on VS

let list = vs![3, 2];
assert_eq!(list.iter().collect::<Vec<_>>(), vec![&3, &2]);
for (index, element) in list.iter().enumerate() {
    assert_eq!(*element, [3, 2][index]);
}

pub fn clear(&self)

Clears list (iterators referencing old chain will still work)

let list = vs![3, 2];
let iter = list.iter();
list.clear();
assert_eq!(iter.len(), 2);
assert_eq!(list.len(), 0);
assert_eq!(list.iter().len(), 0);

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

Extends VS like the Extend trait, but without needing a mutable reference

let list = vs![1, 2, 3];
list.extend(vec![4, 5, 6]);
assert_eq!(list.iter().collect::<Vec<_>>(), vec![&1, &2, &3, &4, &5, &6]);

let list = vs![1, 2, 3];
list.extend(vs![4, 5, 6].iter().cloned());
assert_eq!(list.iter().collect::<Vec<_>>(), vec![&1, &2, &3, &4, &5, &6]);

let list = vs![1, 2, 3];
list.extend(vec![&4, &5, &6].into_iter().cloned());
assert_eq!(list.iter().collect::<Vec<_>>(), vec![&1, &2, &3, &4, &5, &6]);

impl<T: Send + Sync> VoluntaryServitude<T>

pub fn par_extend<I: IntoParallelIterator<Item = T>>(&self, par_iter: I)

Available on crate feature rayon-traits only.

Parallely Extends VS like the ParallelExtend trait, but without a mutable reference

let list = vs![1u8, 2, 3];
list.par_extend(vec![4, 5, 6]);
assert_eq!(list.iter().sum::<u8>(), 21u8);

Trait Implementations

impl<T: Debug> Debug for VoluntaryServitude<T>

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

Formats the value using the given formatter.

impl<T> Default for VoluntaryServitude<T>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, T: 'a + Deserialize<'a>> Deserialize<'a> for VoluntaryServitude<T>

Available on crate feature serde-traits only.

fn deserialize<D: Deserializer<'a>>(des: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl<'a, T: 'a + Copy> Extend<&'a T> for VoluntaryServitude<T>

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

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> Extend<T> for VoluntaryServitude<T>

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

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, T: 'a + Copy> FromIterator<&'a T> for VoluntaryServitude<T>

fn from_iter<I: IntoIterator<Item = &'a T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T> FromIterator<T> for VoluntaryServitude<T>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Send + Sync> FromParallelIterator<T> for VoluntaryServitude<T>

Available on crate feature rayon-traits only.

fn from_par_iter<I: IntoParallelIterator<Item = T>>(par_iter: I) -> Self

Creates an instance of the collection from the parallel iterator par_iter.

impl<T: Send + Sync> ParallelExtend<T> for VoluntaryServitude<T>

Available on crate feature rayon-traits only.

fn par_extend<I: IntoParallelIterator<Item = T>>(&mut self, par_iter: I)

Extends an instance of the collection with the elements drawn from the parallel iterator par_iter.

impl<T: Serialize> Serialize for VoluntaryServitude<T>

Available on crate feature serde-traits only.

fn serialize<S: Serializer>(&self, ser: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.