Struct cfx_storage::Slab

pub struct Slab<T, E: EntryTrait<EntryType = T> = Entry<T>> { /* private fields */ }

Pre-allocated storage for a uniform data type. The modified slab offers thread-safety without giant lock by mimicking the behavior of independent pointer at best.

Resizing the slab itself requires &mut, other operations can be done with &.

Getting reference to allocated slot doesn’t conflict with any other operations. Slab doesn’t check if user get &mut and & for the same slot. User should maintain a layer which controls the mutability of each specific slot. It can be done through the wrapper around the slot index, or in the type which implements EntryTrait<T>.

Allocation and Deallocation are serialized by mutex because they modify the slab link-list.

Implementations

impl<T, E: EntryTrait<EntryType = T>> Slab<T, E>

pub fn with_capacity(capacity: usize) -> Self

Construct a new, empty Slab with the specified capacity.

The returned slab will be able to store exactly capacity without reallocating. If capacity is 0, the slab will not allocate.

It is important to note that this function does not specify the length of the returned slab, but only the capacity. For an explanation of the difference between length and capacity, see Capacity and reallocation.

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

// The slab contains no values, even though it has capacity for more assert_eq!(slab.len(), 0);

// These are all done without reallocating… for i in 0..10 { slab.insert(i); }

// …but this may make the slab reallocate slab.insert(11);

pub fn capacity(&self) -> usize

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

Examples

use cfx_storage::Slab;

use cfx_storage::Slab;
let slab: Slab<i32> = Slab::with_capacity(10);
assert_eq!(slab.capacity(), 10);

pub fn reserve(&mut self, additional: usize) -> Result<()>

Reserve capacity for at least additional more values to be stored without allocating.

reserve does nothing if the slab already has sufficient capacity for additional more values. If more capacity is required, a new segment of memory will be allocated and all existing values will be copied into it. As such, if the slab is already very large, a call to reserve can end up being expensive.

The slab may reserve more than additional extra space in order to avoid frequent reallocations. Use reserve_exact instead to guarantee that only the requested space is allocated.

Panics

Panics if the new capacity overflows usize.

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10); slab.insert(“hello”); slab.reserve(10); assert!(slab.capacity() >= 11);

pub fn reserve_exact(&mut self, additional: usize) -> Result<()>

Reserve the minimum capacity required to store exactly additional more values.

reserve_exact does nothing if the slab already has sufficient capacity for additional more values. If more capacity is required, a new segment of memory will be allocated and all existing values will be copied into it. As such, if the slab is already very large, a call to reserve can end up being expensive.

Note that the allocator may give the slab more space than it requests. Therefore capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Panics

Panics if the new capacity overflows usize.

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10); slab.insert(“hello”); slab.reserve_exact(10); assert!(slab.capacity() >= 11);

pub fn shrink_to_fit(&mut self)

Shrink the capacity of the slab as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements. Also, since values are not moved, the slab cannot shrink past any stored values.

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

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

assert_eq!(slab.capacity(), 10); slab.shrink_to_fit(); assert!(slab.capacity() >= 3);

In this case, even though two values are removed, the slab cannot shrink past the last value.

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

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

slab.remove(0); slab.remove(1);

assert_eq!(slab.capacity(), 10); slab.shrink_to_fit(); assert!(slab.capacity() >= 3);

pub fn clear(&mut self)

Clear the slab of all values.

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

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

slab.clear(); assert!(slab.is_empty());

pub fn len(&self) -> usize

Return the number of stored values.

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

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

use cfx_storage::Slab;

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

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

pub fn iter_mut(&mut self) -> IterMut<'_, T, E>

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<usize> = Slab::with_capacity(10);

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

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

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

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

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10); let key = slab.insert(“hello”);

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

pub 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

use cfx_storage::Slab;
let mut slab: Slab<&str> = Slab::with_capacity(10);
let key = slab.insert("hello").unwrap();

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

assert_eq!(slab[key], "world");
assert_eq!(slab.get_mut(123), None);

pub unsafe fn get_unchecked(&self, key: usize) -> &T

Return a reference to the value associated with the given key without performing bounds checking.

This function should be used with care.

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10); let key = slab.insert(2);

unsafe { assert_eq!(slab.get_unchecked(key), &2); }

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

Return a mutable reference to the value associated with the given key without performing bounds checking.

This function should be used with care.

Examples

use cfx_storage::Slab;
let mut slab: Slab<u32> = Slab::with_capacity(10);
let key = slab.insert(2).unwrap();

unsafe {
    let val = slab.get_unchecked_mut(key);
    *val = 13;
}

assert_eq!(slab[key], 13);

pub fn insert<U>(&self, val: U) -> Result<usize>

where E: WrappedCreateFrom<U, E>,

Insert a value in the slab, returning key assigned to the 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

use cfx_storage::Slab;
let mut slab: Slab<&str> = Slab::with_capacity(10);
let key = slab.insert("hello").unwrap();
assert_eq!(slab[key], "hello");

pub fn allocate(&self) -> Result<usize>

pub fn vacant_entry(&self) -> Result<VacantEntry<'_, T, E>>

Return a handle to a vacant entry allowing for further manipulation.

This function is useful when creating values that must contain their slab key. The returned VacantEntry reserves a slot in the slab and is able to query the associated key.

Examples

use cfx_storage::Slab;
let mut slab: Slab<(usize, &str)> = Slab::with_capacity(10);

let hello = {
    let entry = slab.vacant_entry().unwrap();
    let key = entry.key();
    // this line prevents buggy doc test from triggering.
    entry.insert((key, "hello"));
    key
};

assert_eq!(hello, slab[hello].0);
assert_eq!("hello", slab[hello].1);

pub fn remove(&self, key: usize) -> Result<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

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

let hello = slab.insert(“hello”);

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

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

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

Examples

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

let hello = slab.insert(“hello”); assert!(slab.contains(hello));

slab.remove(hello);

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

pub 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

use cfx_storage::Slab;

let mut slab = Slab::with_capacity(10);

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

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());

Trait Implementations

impl<T, E: EntryTrait<EntryType = T>> Debug for Slab<T, E>

where T: Debug,

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

Formats the value using the given formatter.

impl<T, E: EntryTrait<EntryType = T>> Default for Slab<T, E>

fn default() -> Self

Returns the “default value” for a type.

impl<T, E: EntryTrait<EntryType = T>> Index<usize> for Slab<T, E>

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'a, T, E: EntryTrait<EntryType = T>> IntoIterator for &'a mut Slab<T, E>

type IntoIter = IterMut<'a, T, E>

Which kind of iterator are we turning this into?

type Item = (usize, &'a mut T)

The type of the elements being iterated over.

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

Creates an iterator from a value.

impl<T, E: EntryTrait<EntryType = T> + MallocSizeOf> MallocSizeOf for Slab<T, E>

fn size_of(&self, ops: &mut MallocSizeOfOps) -> usize

Measure the heap usage of all descendant heap-allocated structures, but not the space taken up by the value itself.

impl<T, E: EntryTrait<EntryType = T>> Sync for Slab<T, E>