`dragon.managed_memory` – Managed Memory Cython Adapter

This page documents the Cython interface for the Dragon Managed Memory library. For a description of Managed Memory, Pools, and general functionality please refer to this document.

All functions and variables listed as C language are implemented with the cdef keyword and are not directly accessible from python-space.

Factory init methods are used in place of pythonic constructors as they require Python object arguments, while some instances require the use of C structs.

Objects

MemoryAlloc

class MemoryAlloc

Python object for managing allocations made in the pool.

dragonMemoryDescr_t mem_descr: Memory descriptor, used internally.

size_t mem_size: Size of the allocated memory. Used for returning memoryviews.

static attach(serialized_bytes)

Attaches a new MemoryAlloc object to an existing serialized memory descriptor. Must be explicitly cleaned up using the detach method.

Parameters: serialized_bytes – Bytes object containing a serialized memory descriptor
Returns: MemoryAlloc object
Return type: MemoryAlloc
Raises: RuntimeError

get_memview()

Returns a memoryview instance of the underlying memory allocation.

Returns: memoryview
Return type: memoryview
Raises: RuntimeError

serialize()

Serializes the underlying memory descriptor and returns it as a bytes object.

Returns: bytes object of the serialized descriptor
Return type: bytes
Raises: RuntimeError

detach()

Detaches from the underlying memory.

Raises: RuntimeError

MemoryAllocations

class MemoryAllocations

Python object for retrieving and searching through a current list of allocations in the pool manifest.

dragonMemoryPoolAllocations_t allocs: Underlying C struct

alloc_type(idx)

Returns the type of the given allocation.

Returns: AllocType of the specified allocation index
Return type: AllocType
Raises: RuntimeError (index out of bounds)

alloc_id(idx)

Return the unique ID of the given allocation

Returns: ID of the specified allocation
Return type: int
Raises: RuntimeError (index out of bounds)

MemoryPool

class MemoryPool

Python object for creating, attaching to, etc. pools. Memory allocations and frees are performed through this object, as well as retrieving a list of allocations through a MemoryAllocations object.

dragonMemoryPoolDescr_t _pool_hdl: Internal C struct pool descriptor handle.

static attach(pool_serialized)

Attaches to an existing memory pool. Cleaning requires an explicit call to detach.

Parameters: pool_serialized – bytes object of a serialized pool descriptor.
Returns: MemoryPool object
Return type: MemoryPool
Raises: DragonPoolAttachFail

destroy()

Destroys the pool created by this object.

Raises: DragonPoolError

detach(serialize=False)

Detaches the pool handle owned by this object.

Parameters: serialize – Boolean to optionally store a serializer before detaching
Raises: DragonPoolError

serialize()

Serialized the pool descriptor held by this object. Used for passing to other processes for attaching. Stores a copy in the object when called the first time.

Returns: Bytes object of the pool serializer struct.
Return type: bytes
Raises: DragonPoolError

alloc(size_t size)

Allocate a new chunk of memory of size size in the memory pool. Returns a new MemoryAlloc object on success.

Parameters: size – Size in bytes to allocate
Returns: MemoryAlloc object with new allocation
Return type: object
Raises: DragonPoolError

alloc_blocking(size_t size, timeout=None)

Allocate a new chunk of memory of size size in the memory pool. Returns a new MemoryAlloc object on success. If size block is unavailable, it blocks timeout seconds waiting for an allocation. If timeout is None, it blocks without timeout.

Parameters: size – Size in bytes to allocate
Returns: MemoryAlloc object with new allocation
Return type: object
Raises: DragonPoolException

free(MemoryAlloc mem_obj)

Frees the allocation held by mem_obj in the pool.

Parameters: mem_obj – The MemoryAlloc object holding the descriptor for the given allocation to free
Raises: RuntimeError

get_allocations()

Retrieves a list of all active allocations in the memory pool.

Returns: MemoryAllocations object
Return type: object
Raises: DragonPoolError

allocation_exists(alloc_type, alloc_id)

Given a type and ID, check whether a given allocation exists in the pool manifest.

Parameters

alloc_type – AllocType enum of the allocation
alloc_id – Unique ID of the allocation

Returns

True or False

Return type

Boolean

Raises

DragonPoolError

get_alloc_by_id(alloc_type, alloc_id)

Retrieve a specific allocation from the pool by its type and unique ID.