Struct defrag::Pool
[−]
[src]
pub struct Pool { /* fields omitted */ }
Pool
contains a "pool" of memory which can be allocated and used
Pool memory can be accessed through the alloc
and alloc_slice
methods,
returning memory protected behind a Mutex
. The Mutex allows the Pool to
defragment application memory when it is not in use, solving the problem
of memory fragmentation for embedded systems.
It is up to the user to call defrag
and clean
when they can, to keep
memory defragmeneted. These methods are not yet profiled, but it should
be expected that clean
will take less than 10ms and defrag
will take
less than 100ms on most platforms.
Methods
impl Pool
[src]
fn new(size: usize, indexes: u16, index_cache: u16) -> Result<Pool>
Create a new pool of the requested size and number of indexes.
size
is total size in bytes of the internal block pool. Some of this space
will be used to keep track of the size and index of the allocated data.
indexes
are the total number of indexes available. This is the maximum
number of simultanious allocations that can be taken out of the pool.
Allocating a Mutex uses an index, dropping the Mutex frees the index.
index_cache
is the maximum number of indexes that can be stored in the
cache. If there are no indexes in the cache, the maximum lookup time to
obtain an index is O(indexes.len()). Setting index_cache == indexes
will ensure that indexes are found in O(1). For most applications,
setting index_cache = 1/10 of indexes or less is recommended
unsafe fn from_raw(raw: *mut RawPool) -> Pool
!! UNSTABLE !!
get a Pool from a RawPool that you have initialized.
unsafe: currently alloc::heap::dealloc
will be called on the
memory when Pool
it goes out of scope, so you must ensure that
Pool does not go out of scope... or something
fn alloc<T: Default>(&self) -> Result<Mutex<T>>
attempt to allocate memory of type T, returning Result<Mutex<T>>
.
If Ok(Mutex<T>)
, the memory will have been initialized to T.default
and can be unlocked and used by calling Mutex.try_lock
.
This function uses a "best fit" approach with bins to speed it up. It will search the lowest bin that might fit and will return the free block with the closest fit.
The longest time this can take is O(f + i)
where f
is the number of
free blocks in the lowest bin that matches and i
is the total number
of indexes.
For error results, see Error
.
fn alloc_fast<T: Default>(&self) -> Result<Mutex<T>>
See Pool.alloc
for description of use.
This allocation method should be used if allocation is time-critical.
Unlike Pool.alloc
, this method guarantees O(i) allocation time,
where i
is the number of indexes (but is affected by index_cache
).
alloc_fast
works by only looking in freed bins that are guaranteed
to fit the requested size of memory. On average, alloc_fast
will lead
to more fragmentation of memory, and therefore require defrag
to be
called more often.
Also, this method may return Error::Fragmented when Pool.alloc
returns Ok, due to the fact that not all possible free blocks were
checked.
fn alloc_slice<T: Default>(&self, len: u16) -> Result<SliceMutex<T>>
Attempt to allocate a slice of memory with len
of T
elements,
returning Result<SliceMutex<T>>
.
If Ok(SliceMutex<T>)
, all elements of the slice will have been
initialized to T.default
and can be unlocked and used by calling
Mutex.try_lock
.
For additional information, see Pool.alloc
fn alloc_slice_fast<T: Default>(&self, len: u16) -> Result<SliceMutex<T>>
See Pool.alloc_sice
for description of use.
See Pool.alloc_fast
for description of performance characteristics.
fn display(&self) -> DisplayPool
call this to be able to printout the status of the Pool
.
fn clean(&self)
clean the Pool
, combining contigous blocks of free memory.
fn defrag(&self)
!! UNSTABLE !!
defragment the Pool
, combining blocks of
used memory and increasing the size of the
heap.
This method is currently blocking, options are being looked into to guarantee some kind of maximum time per call.
fn size(&self) -> usize
get the total size of the Pool
in bytes
fn len_indexes(&self) -> u16
get the total number of indexes in the Pool