dragon.heapmanager – Heap allocations through the Heap Manager library
This page documents the Cython interface for the Dragon Heap Manager library. For a description of the Heap Manager and its functionality please refer to [link to heap manager doc goes here]. Example usage of this API can be found at the bottom of this document.
All functions and variables listed as C language are implemented with the cdef keyword and are not directly accessible from python-space.
Objects
BitSet
- class BitSet
BitSet object. For internal testing use of the bitset library used by the heapmanager library.
-
dragonBitSet_t _set
BitSet struct handle
-
void *_mem_ptr
Pointer to the heap this bitset is part of
- _attach
Whether this bitset was initialzed to a new heap or attached to an existing one
- classmethod init(num_bits, space)
Initializes a new BitSet object handle to the provided memory space
- Parameters
num_bits (size_t) – Number of bits the handle should track
space – A bytearray or memoryview object the bitset should attach to
- Returns
BitSet object
- Return type
- Raises
RuntimeError
- classmethod attach(space)
Attaches a new BitSet object handle to an existing memory space with an initialized BitSet
- Parameters
space – A bytearray or memoryview object that already has an initialized BitSet
- Returns
BitSet object
- Return type
- Raises
RuntimeError
- classmethod size(num_bits)
Get the needed size for the BitSet based on the number of bits to track
- Parameters
num_bits (size_t) – Number of bits to be tracked by the BitSet handle
- Returns
Required memory size for metadata and bits to track
- Return type
size_t
- detach()
Detach the BitSet from its heap. Call after using attach.
- Raises
RuntimeError if not attached
- destroy()
Destroy the BitSet from its heap. Call after using init.
- Raises
RuntimeError if not initialized
- get_num_bits()
- Returns
The number of bits in the set
- Return type
size_t
- get_bit(idx)
- Returns
The state of the bit at the specified index
- Return type
unsigned char
- Raises
RuntimeError if out of index range
- set_bit(idx)
Set the specified bit index to 1 unconditionally.
- Parameters
idx (int) – Index to set to 1
- Raises
Runtime error if out of index range
- reset_bit(idx)
Set the specified bit index to 0 unconditionally.
- Parameters
idx (int) – Index to set to 0
- Raises
Runtime error if out of index range
- right_zeroes(idx)
- dump(title, indent)
-
dragonBitSet_t _set
Heap
- class Heap
Heap object. Used to manage allocated memory. Can be explicitly detached from a heap or destroyed, otherwise GC should call the correct function when the objects lifetime ends.
- num_segments
- segment_size
- num_freelists
- recovery_needed
- init_handle
- exclusive_access
Return a pointer to the exlusive access mutex
- classmethod size(max_sz_pwr, min_sz_pwr, alignment)
Calculate the necessary memory size for the given powers of two and segment alignment.
- Parameters
max_sz_pwr (size_t) – Power of 2 to allocate for the heap
min_sz_pwr (size_t) – Power of 2 for minimum segment size
alignment (size_t) – Memory alignment size (Multiples of 8)
- Returns
Size of heap to be allocated
- Return type
size_t
- Raises
RuntimeError
- classmethod init(max_sz_pwr, min_sz_pwr, alignment, mem_addr)
Not to be confused with the default constructor. Takes the same parameters as the size class method as well as a pointer to an allocated heap.
- Parameters
max_sz_pwr (size_t) – Power of 2 to allocate for the heap
min_sz_pwr (size_t) – Power of 2 for minimum segment size
alignment (size_t) – Memory alignment size (Multiples of 8)
mem_addr (bytearray) – Bytearray or memoryview object to initialize heap with
- Returns
New heap manager
- Return type
- Raises
RuntimeError
- classmethod attach(mem_addr)
Creates and attaches a new handle to an existing heap.
- detach()
Detaches the handle from its heap.
- Raises
RuntimeError
- destroy()
Destroys the handle. To be used when the object was created using init.
- Raises
RuntimeError
- malloc(size)
Allocates the requested size of memory in the heap manager. Returns a new DragonMem object to hold the pointer.
- Parameters
size (size_t) – Size of memory to request from the heap manager
- Returns
New memory object
- Return type
MemoryView
- Raises
RuntimeError
- free(mem_obj)
Free the memory held by the memoryview object that was allocated using the malloc method.
- Parameters
mem_obj (memoryview) – Memory object
- Returns
None
- Raises
RuntimeError if recovery is needed first
- recover()
Perform heap recovery when corrupted.
- Returns
None
- Raises
RuntimeError if recovery needed flag is not set
- get_stats()
Get an object that contains statistics about the heap.
- Returns
Statistics object
- Return type
MemStat
- Raises
RuntimeError
- dump(title)
Print out a dump of heap information to stdout
- Parameters
title (str) – Title to include at the top of the output
- Returns
None
- Raises
RuntimeError
- dump_to_str(title)
Return a dump of heap information to a string
- Parameters
title (str) – Title to include at the top of the output
- Returns
Heap info
- Return type
String
- Raises
RuntimeError
Example usage
from dragon.malloc.heapmanager import Heap
# Get a 4GB Heap with 4k minimum segment sizes
heap_size = Heap.size(32, 12, 4096)
# Allocate a memory object
memobj = bytearray(heap_size)
# Initialize the handle
heap_handle = Heap.init(32, 12, 4096, bytearray)
# Attach another handle
heap_handle_2 = HeapHandle.attach(bytearray)
# Get some memory from the heap
tmp_mem = heap_handle.malloc(32)
# Do some stuff with the memory...
tmp[0:10] = b'Hello world'
# Free the memory
# When recovery is needed, runtime exception will be thrown
try:
heap_handle.free(tmp_mem)
except:
heap_handle.recover()
heap_handle.free(tmp_mem)
# Detach the other handle
heap_handle_2.detach()
# Dump heap info
heap_handle.dump("Heap info")
# Destroy the handle
heap_handle.destroy()