Struct pinned_slab::Slab

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

The slab-allocator (also known as an object pool) struct.

Methods

impl<T> Slab<T>

pub fn new() -> Self

Construct a new, empty Slab.

The function does not allocate and the returned slab will have no capacity until insert is called or capacity is explicitly reserved.

Examples

let slab: Slab<i32> = Slab::new();

pub fn len(&self) -> usize

Return the number of stored values.

Examples

let mut slab = Slab::new();

for i in 0..3 {
    slab.insert(i);
}

assert_eq!(3, slab.len());

pub fn is_empty(&self) -> bool

Return true if there are no values stored in the slab.

Examples

let mut slab = Slab::new();
assert!(slab.is_empty());

slab.insert(1);
assert!(!slab.is_empty());

pub fn contains(&self, key: usize) -> bool

Return true if a value is associated with the given key.

Examples

let mut slab = Slab::new();

let (hello, _) = slab.insert("hello");
assert!(slab.contains(hello));

slab.remove(hello);

assert!(!slab.contains(hello));

pub fn capacity(&self) -> usize

Return the number of values the slab can store without reallocating.

This will always be a multiple of CHUNK_SIZE.

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

Return an iterator over the slab.

This function should generally be avoided as it is not efficient. Iterators must iterate over every slot in the slab even if it is vacant. As such, a slab with a capacity of 1 million but only one stored value must still iterate the million slots.

Examples

let mut slab = Slab::new();

for i in 0..3 {
    slab.insert(i);
}

let mut iterator = slab.iter();

assert_eq!(iterator.next(), Some((0, &0)));
assert_eq!(iterator.next(), Some((1, &1)));
assert_eq!(iterator.next(), Some((2, &2)));
assert_eq!(iterator.next(), None);

pub unsafe fn iter_mut(&mut self) -> IterMut<T>

Return an iterator that allows modifying each value.

This function should generally be avoided as it is not efficient. Iterators must iterate over every slot in the slab even if it is vacant. As such, a slab with a capacity of 1 million but only one stored value must still iterate the million slots.

Examples

let mut slab = Slab::new();

let (key1, _) = slab.insert(0);
let (key2, _) = slab.insert(1);

for (key, val) in unsafe { slab.iter_mut() } {
    if key == key1 {
        *val += 2;
    }
}

assert_eq!(slab[key1], 2);
assert_eq!(slab[key2], 1);

Safety

This effectively un-pins every entry. The caller has to make sure that this is definitely what they want to do, e.g. they won't invalidate any pointers to these values.

pub fn get(&self, key: usize) -> Option<&T>

Return a reference to the value associated with the given key.

If the given key is not associated with a value, then None is returned.

Examples

let mut slab = Slab::new();
let (key, _) = slab.insert("hello");

assert_eq!(slab.get(key), Some(&"hello"));
assert_eq!(slab.get(123), None);

pub unsafe fn get_mut(&mut self, key: usize) -> Option<&mut T>

Return a mutable reference to the value associated with the given key.

If the given key is not associated with a value, then None is returned.

Examples

let mut slab = Slab::new();
let (key, _) = slab.insert("hello");

unsafe {
    *slab.get_mut(key).unwrap() = "world";
}

assert_eq!(*unsafe { slab.get_mut(key) }.unwrap(), "world");
assert_eq!(unsafe { slab.get_mut(123) }, None);

Safety

This effectively un-pins the entry at key. The caller has to make sure that this is definitely what they want to do, e.g. they won't invalidate any pointers to this value.

pub fn insert(&mut self, val: T) -> (usize, &T)

Insert a value in the slab, returning key assigned to the value and a reference to that value.

The returned key can later be used to retrieve or remove the value using indexed lookup and remove. Additional capacity is allocated if needed. See Capacity and reallocation.

Panics

Panics if the number of elements in the vector overflows a usize.

Examples

let mut slab = Slab::new();
let (key, value) = slab.insert("hello");
assert_eq!(*value, "hello");
assert_eq!(slab[key], "hello");

Insert a value into the Slab and get the key for the value.

pub fn remove(&mut self, key: usize) -> T

Remove and return the value associated with the given key.

The key is then released and may be associated with future stored values.

Panics

Panics if key is not associated with a value.

Examples

let mut slab = Slab::new();

let (hello, _) = slab.insert("hello");

assert_eq!(slab.remove(hello), "hello");
assert!(!slab.contains(hello));

pub fn free_unused(&mut self)

Free any empty chunks.

pub unsafe fn retain<F>(&mut self, f: F) where
    F: FnMut(usize, &mut T) -> bool, 

Retain only the elements specified by the predicate.

In other words, remove all elements e such that f(usize, &mut e) returns false. This method operates in place and preserves the key associated with the retained values.

Examples

let mut slab = Slab::new();

let (k1, _) = slab.insert(0);
let (k2, _) = slab.insert(1);
let (k3, _) = slab.insert(2);

unsafe {
   slab.retain(|key, val| key == k1 || *val == 1);
}

assert!(slab.contains(k1));
assert!(slab.contains(k2));
assert!(!slab.contains(k3));

assert_eq!(2, slab.len());

Safety

This effectively un-pins every entry. The caller has to make sure that this is definitely what they want to do, e.g. they won't invalidate any pointers to these values.

Trait Implementations

impl<T: Clone> Clone for Slab<T>

fn clone(&self) -> Slab<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Slab<T>

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

Formats the value using the given formatter.

impl<T> Default for Slab<T>

fn default() -> Self

Returns the "default value" for a type.

impl<T> Index<usize> for Slab<T>

type Output = T

The returned type after indexing.

fn index(&self, key: usize) -> &T

Performs the indexing (container[index]) operation.

impl<'a, T> IntoIterator for &'a Slab<T>

type Item = (usize, &'a T)

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a, T>

Creates an iterator from a value.