Struct indexed::Pool

source ·

pub struct Pool<T: Indexed> { /* private fields */ }

Expand description

A Vec-like, no reallocation collection. Elements in a Pool should not be zero sized type, or the construction will panic.

Implementations

source

impl<T: Indexed> Pool<T>

source

pub fn new() -> Box<Self>

Creates a new pool that drops its elements on destruction.

pub fn new_unmanaged() -> Box<Self>

Creates a new pool that does not drop its elements on destruction. It is up to the user to drop the elements manually to avoid memory leaks.

pub fn push(&mut self, value: T)

Appends an element to the back of a pool.

Panics

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

pub unsafe fn write(&mut self, index: usize, value: T)

Overwrites a new value into a pool at given index without reading or dropping the old value.

Safety

This operation is marked unsafe because it accepts an index as an offset which acts like a raw pointer.

It does not drop the contents of the existing self[index] element. This is safe, but it could leak allocations or resources, so care must be taken not to overwrite an object that should be dropped.

Additionally, it does not drop value. Semantically, value is moved into self[index].

This is appropriate for initializing uninitialized memory.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the given Pool. The collection may reserve more space because the increasing size must be multiple of underlying chunk_len(). After calling reserve, capacity will be greater than or equal to self.new_index() + additional. Does nothing if capacity is already sufficient.

Panics

Panics if the new capacity overflows usize.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = Pool::<Foo>::new();

pool.reserve( 0 );
assert_eq!( pool.capacity(), 0 );

pool.reserve( 1 );
let cap = pool.capacity();
assert!( cap >= 1 );

pool.reserve( 1 );
assert_eq!( pool.capacity(), cap );

pool.reserve( 1024 );
assert!( pool.capacity() >= 1024 );

source

pub fn len(&self) -> usize

Returns the number of elements in the pool, also referred to as its ‘length’.

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = pool!( Foo[ "a", "b", "c" ]);
assert_eq!( pool.len(), 3 );

source

pub unsafe fn set_len(&mut self, len: usize)

Sets the length of a pool.

This will explicitly set the size of the pool, without actually modifying its buffers, so it is up to the caller to ensure that the pool is actually the specified size.

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: char }}

let mut pool = pool!( Foo[ 'r', 'u', 's', 't' ]);

unsafe {
    std::ptr::drop_in_place( &mut pool[3] );
    pool.set_len( 3 );
}

assert_eq!( pool.len(), 3 );
assert_eq!( pool.iter().map( |e| e.inner ).collect::<Vec<_>>(), vec!['r', 'u', 's'] );

In this example, there is a memory leak since the memory locations owned by the first Name were not freed prior to the set_len call:

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

static mut COUNT: usize = 0;

struct Name { index: usize, text: String }

impl_indexed!{ Name{ index: usize }}

impl Drop for Name { fn drop( &mut self ) { unsafe{ COUNT += 1; }}}

impl From<&'static str> for Name {
    fn from( s: &'static str ) -> Self {
        Name{ index: <Self as Indexed>::null(), text: s.to_string() }
    }
}

let mut pool = pool!( Name[ "abc", "def", "g" ]);

unsafe {
    std::ptr::drop_in_place( &mut pool[2] );
    std::ptr::drop_in_place( &mut pool[1] );
    pool.set_len( 0 );
}

assert_eq!( unsafe{ COUNT }, 2 );

In this example, the pool gets expanded from zero to four items without any memory allocations occurring, resulting in pool values of unallocated memory:

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = Pool::<Foo>::new();
unsafe { pool.set_len( 3 ); }

source

pub fn capacity(&self) -> usize

Returns the number of elements the vector can hold without more allocating.

Note: the purpose of this method is not to avoid reallocation, which could not happen at all, but to grow the buffer for next incomming write()s.

source

pub fn non_null(&self) -> NonNull<Self>

Returns the pool’s NonNull pointer.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: i32 }}

let mut pool = Pool::<Foo>::new();
let p = pool.non_null();

assert_eq!( p, std::ptr::NonNull::new( Box::into_raw( pool )).unwrap() );

source

pub fn pool(value: &T) -> &Self

Obtains reference of the pool of an element.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: usize }}

let mut pool = Pool::<Foo>::new();

for i in 0..1024 {
    pool.push( i.into() );
}

for i in 0..1024 {
    assert!( pool.non_null().as_ptr() as *const Pool<Foo> == pool[i].pool() );
}

source

pub unsafe fn pool_mut(value: &T) -> &mut Self

Obtains mutable reference of the pool from an element.

Safety

This operation is marked unsafe because it obtains a mutable reference of the Pool from one of its immutable element, which may violate the memory safety rule “only one mutable reference, or none but multiple immutable references”.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: usize }}

let mut pool = Pool::<Foo>::new();

for i in 0..1024 {
    pool.push( i.into() );
}

for i in 0..1024 {
    assert_eq!( pool.non_null().as_ptr(),
                unsafe{ pool[i].pool_mut() as *mut Pool<Foo>});
}

source

pub fn pool_non_null(value: &T) -> NonNull<Self>

Obtains NonNull pointer of the pool from an element.

source

pub fn new_index(&self) -> usize

Returns the expected index for the next new element to be push()ed in.

source

pub fn is_empty(&self) -> bool

Returns true if the pool contains no elements.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = Pool::new();
assert!( pool.is_empty() );

pool.push( Foo::from( "foo" ));
assert!( !pool.is_empty() );

source

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

Returns an iterator over the pool.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = pool!( Foo[ "abc", "def", "g" ]);
let mut iter = pool.iter();

assert_eq!( iter.next().unwrap().inner, "abc" );
assert_eq!( iter.next().unwrap().inner, "def" );
assert_eq!( iter.next().unwrap().inner, "g"   );
assert!( iter.next().is_none() );

source

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

Returns an iterator that allows modifying each value.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: i32 }}

let mut pool = pool!( Foo[ 0, 1, 2 ]);

pool.iter_mut().for_each( |elem| { elem.inner += 10; });

assert_eq!( pool.iter().map( |e| e.inner ).collect::<Vec<_>>(), vec![ 10, 11, 12 ]);