Struct maskerad_memory_allocators::StackAllocatorCopy

pub struct StackAllocatorCopy { /* fields omitted */ }

A stack-based allocator for data implementing the Copy trait.

It manages a MemoryChunk to:

• Allocate bytes in a stack-like fashion.

• Store different types of objects in the same storage.

Differences with StackAllocator

This stack allocator slightly differs from the non-copy stack allocator. The non-copy stack allocator must extract some metadata (the vtable) about the object it will allocate, to be able to call the drop function of the object when needed. However, a type implementing the Copy trait doesn't, and can't, implement Drop. There is no need to store extra informations about those types, they don't have destructors.

Instantiation

When instantiated, the memory chunk pre-allocate the given number of bytes.

Allocation

When an object is allocated in memory, the StackAllocator:

• Asks a pointer to a memory address to its memory chunk,

• Place the object in this memory address,

• Update the first unused memory address of the memory chunk according to an offset,

• And return a mutable reference to the object which has been placed in the memory chunk.

This offset is calculated by the size of the object, its memory-alignment and an offset to align the object in memory.

Roll-back

This structure allows you to get a marker, the index to the first unused memory address of the memory chunk. A stack allocator can be reset to a marker, or reset entirely.

When the allocator is reset to a marker, the memory chunk will set the first unused memory address to the marker.

When the allocator is reset completely, the memory chunk will set the first unused memory address to the bottom of its stack.

Methods

impl StackAllocatorCopy

fn with_capacity(capacity: usize) -> Self

Creates a StackAllocatorCopy with the given capacity, in bytes.

Example

#![feature(alloc)]
use maskerad_memory_allocators::StackAllocatorCopy;

let allocator = StackAllocatorCopy::with_capacity(100);
assert_eq!(allocator.storage().borrow().capacity(), 100);

fn storage(&self) -> &RefCell<MemoryChunk>

Returns an immutable reference to the memory chunk used by the allocator.

fn alloc<T: Copy, F>(&self, op: F) -> &mut T where
    F: FnOnce() -> T, 

Allocates data in the allocator's memory.

Panics

This function will panic if the allocation exceeds the maximum storage capacity of the allocator.

Example

use maskerad_memory_allocators::StackAllocatorCopy;

let allocator = StackAllocatorCopy::with_capacity(100);

let my_i32 = allocator.alloc(|| {
    26 as i32
});
assert_eq!(my_i32, &mut 26);

fn marker(&self) -> usize

Returns the index of the first unused memory address.

Example

use maskerad_memory_allocators::StackAllocatorCopy;

let allocator = StackAllocatorCopy::with_capacity(100); //100 bytes

//Get the raw pointer to the bottom of the allocator's memory chunk.
let start_allocator = allocator.storage().borrow().as_ptr();

//Get the index of the first unused memory address.
let index_current_top = allocator.marker();

//Calling offset() on a raw pointer is an unsafe operation.
unsafe {
    //Get the raw pointer, with the index.
    let current_top = start_allocator.offset(index_current_top as isize);

    //Nothing has been allocated in the allocator,
    //the top of the stack is the bottom of the allocator's memory chunk.
    assert_eq!(current_top, start_allocator);
}

fn reset(&self)

Reset the allocator completely.

Example

use maskerad_memory_allocators::StackAllocatorCopy;


let allocator = StackAllocatorCopy::with_capacity(100); // 100 bytes.

//When nothing has been allocated, the first unused memory address is at index 0.
assert_eq!(allocator.marker(), 0);

let an_u8 = allocator.alloc(|| {
    15 as u8
});
assert_ne!(allocator.marker(), 0);

let bob = allocator.alloc(|| {
    0xb0b as u64
});

allocator.reset();

//The allocator has been totally reset, allocation will now start at index 0.
assert_eq!(allocator.marker(), 0);

fn reset_to_marker(&self, marker: usize)

Reset partially the allocator, allocations will occur from the index given by the marker.

Example

use maskerad_memory_allocators::StackAllocatorCopy;

let allocator = StackAllocatorCopy::with_capacity(100); // 100 bytes.

//When nothing has been allocated, the first unused memory address is at index 0.
assert_eq!(allocator.marker(), 0);

let an_i32 = allocator.alloc(|| {
    45 as i32
});

//After the i32 allocation, get the index of the first unused memory address in the allocator.
let index_current_top = allocator.marker();
assert_ne!(index_current_top, 0);

let an_i64 = allocator.alloc(|| {
    450 as i64
});

assert_ne!(allocator.marker(), index_current_top);

allocator.reset_to_marker(index_current_top);

//The allocator has been partially reset, new allocations will occur from the index given
//by the marker.

assert_eq!(allocator.marker(), index_current_top);