`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.