Managed Memory

Description

Dragon memory pools and memory allocations are shared memory allocations that can be attached to both on-node and off-node. Attaching on-node to a pool means that a process can create allocations within the pool. Attaching to a memory allocation on-node means a process can get a pointer to the allocation.

Structures and Constants

Here are structures and constants for creating and sharing memory pools and memory pool allocations. These structures and constants are found in managed_memory.h.

enum dragonMemoryPoolType_t

The type of memory pool.

For future use. Currently, the only valid value is DRAGON_MEMORY_TYPE_SHM.

Values:

enumerator DRAGON_MEMORY_TYPE_SHM

enumerator DRAGON_MEMORY_TYPE_FILE

enumerator DRAGON_MEMORY_TYPE_PRIVATE

enum dragonMemoryPoolGrowthType_t

The growth type for the pool.

For future use. Currently, the only valid value is DRAGON_MEMORY_GROWTH_NONE.

Values:

enumerator DRAGON_MEMORY_GROWTH_NONE

enumerator DRAGON_MEMORY_GROWTH_UNLIMITED

enumerator DRAGON_MEMORY_GROWTH_CAPPED

struct dragonMemoryPoolAttr_t

The attributes of the Dragon Memory Pool.

These are the attributes of a memory pool. Some are settable by the user. Some are read-only values and returned when requested by the user via the dragon_memory_pool_getattr function (not yet implemented). A few of these attributes are not yet implemented.

Public Members

size_t allocatable_data_size

The size of the original data segment of the pool. Ignored if set by user. This is the allocatable size of the pool which does not include meta information.

size_t total_data_size

The total size of the data segment include meta information. Ignored if set by user. This is the total size of the data segment including meta information.

size_t data_min_block_size

The requested minimum allocation size from the pool. The actual minimum block size is reported via dragon_memory_pool_getattr. All allocations will be at least this size.

size_t manifest_allocated_size

The size in bytes of the manifest. Ignored if set by user.

size_t manifest_table_size

The size in bytes of the internal allocation table. Ignored if set by user.

size_t manifest_heap_size

The size in bytes of the internal heap manager. Ignored if set by user.

size_t segment_size

The requested size of segments when pool size is increased by the user. The actual segment size may be larger. The actual segment size will be reported by dragon_memory_pool_getattr.

size_t max_size

The requested maximum size of the memory pool. The actual maximum size will not be less than this but could be bigger based on requirements of the underlying heap representation. The actual maximum size will be reported by dragon_memory_pool_getattr.

size_t max_allocatable_block_size

The maximum size of any allocatable block. Ignored if set by the user. This is the biggest block allocation this pool can support when empty.

dragonMemoryPoolType_t mem_type

The type of memory this pool supports. Currently only SHM memory pools are supported.

dragonMemoryPoolGrowthType_t growth_type

The type of growth allowed on this memory pool. See dragonMemoryPoolGrowthType_t for an explanation. Currently ignored.

mode_t mode

The mode to be used for the memory pool. This provides the umask for any file-backed permissions related to this memory pool.

size_t npre_allocs

The number of preallocation sizes to do on this pool. To support fast allocation, a number of preallocations may be specified. This is the number of preallocation sizes that are specified in pre_allocs.

size_t *pre_allocs

The pre_allocs is an array of power of 2 preallocations to be made for fast allocation of certain sizes of blocks. Position 0 in this array indicates the number of preallocations to make with the minimum block size. Position 1 in the array is the number of allocations to make with two times the minimum block size. Each position, n, in the array indicates the number of allocations to make with 2**n times the block size.

char *mname

The name of the manifest file when backed by a file. This value is ignored if set by the user.

char **names

An array data segment file names when backed by a file. The array of names is of length 1 + n_segments. This value is ignored if set by the user.

struct dragonMemoryPoolDescr_t

This is an opaque handle to a memory pool.

When a memory pool is created, the opaque descriptor is initialized to correspond to the pool in the current process. Memory pool descriptors reside in process local storage in the process in which they are created or attached. If you wish to share a pool descriptor with another process, you must serialize the pool descriptor and the serialized descriptor can be shared with another process. The other process must then attach to the memory pool to initialize its own pool descriptor.

enum dragonMemoryAllocationType_t

Specifies the memory allocation type.

Dragon supports the allocation of memory based on a specific type or purpose. The generic allocation type is data and should be used by user-level code. Internally to Dragon, channel and channel buffer allocation types are also allowable.

Values:

enumerator DRAGON_MEMORY_ALLOC_DATA

Allocation is used for general-purpose data.

enumerator DRAGON_MEMORY_ALLOC_CHANNEL

Internal Use Only.

enumerator DRAGON_MEMORY_ALLOC_CHANNEL_BUFFER

Internal Use Only.

struct dragonMemoryDescr_t

This is an opaque handle to a memory allocation.

When Dragon pool memory is allocated, a memory descriptor is initialized for the current process. These memory descriptors may be shared with other processes by first serializing them, and then passing the serialized descriptor to another process. The other process must then attach to the memory allocation using the serialized descriptor. Attaching and allocating are the two means of initializing a memory descriptor.

struct dragonMemoryPoolSerial_t

This is the type of a serialied memory pool descriptor.

It should be treated as binary data with the given length.

Public Members

size_t len

The length of the serialized descriptor in bytes.

struct dragonMemorySerial_t

A serialized memory descriptor.

This is the type of binary data that may be shared with other processes when a memory descriptor should be shared between processes.

Public Members

size_t len

The length of the serialized descriptor in bytes.

uint8_t *data

The serialized descriptor data to be shared.

struct dragonMemoryPoolAllocations_t

A structure for getting all the memory allocations in a pool.

When desired, a pool can be queried to return all the allocations within the pool. You do this by calling dragon_memory_pool_get_allocations or the type specific dragon_memory_pool_get_type_allocations.

Pool Lifecycle Management

dragonError_t dragon_memory_attr_init(dragonMemoryPoolAttr_t *attr)

Initialze memory pool attributes.

Memory pools have attributes that can be specified to customize the behavior and characteristics of the memory pool. Call this method first to initialize all attributes to default values, before customizing the values for your application’s specifics.

Parameters:

attr – is a attribute structue and may result in mallocing space, so destroy should be called when done with the structure.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_attr_destroy(dragonMemoryPoolAttr_t *attr)

Destroy the memory pool attribute structure.

Any mallocs that were performed by dragon_memory_attr_init are freed by calling this destroy function. Any mallocs that were executed done by a caller of this function are the responsibility of the code calling this. After user code is done initig the pool, be sure to set any pointer field to NULL or this function will return an error code to try and catch unfreed memory that was mistakenly left around.

Parameters:

attr – is the attribute structure to clean up.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_create(dragonMemoryPoolDescr_t *pool_descr, size_t bytes, const char *base_name, const dragonM_UID_t m_uid, const dragonMemoryPoolAttr_t *attr)

Creates a memory pool of size bytes.

Creates a memory pool of usable size bytes. base_name is a null-terminated character string to use if the memory is backed by a file or shared memory. The attributes attr specifies customizations of the memory or is ignored if set to NULL. If attr is provided and the value of mem_type in it set to DRAGON_MEMORY_TYPE_PRIVATE, then base_name is ignored.

The memory pool descriptor pool_descr is returned once the allocation is satisfied. pool_descr can then be used for memory allocations. pool_descr can be serialized and shared with other processes that want to allocate memory from it.

Note that depending on the value of nodemask in attr, the memory for the pool may or may not be faulted in.

Parameters:

• pool_descr – is a structure pointer provided by the user, pointing at space that can be initialized.

• bytes – is the size of the memory pool in bytes.

• base_name – is the base of the name of the shared memory segement which is to be mapped into memory.

• m_uid – is the memory pool identifer to uniquely identify this pool.

• attr – are the attributes to be applied when creating this pool. Providing NULL for this argument will use default attributes for the pool.

Returns:

DRAGON_SUCCESS or an error code.

dragonError_t dragon_memory_pool_destroy(dragonMemoryPoolDescr_t *pool_descr)

Destroys the memory pool described by pool_descr. Any outstanding allocations from the memory pool become invalid.

Returns:

DRAGON_SUCCESS or an error code.

size_t dragon_memory_pool_max_serialized_len()

Provide a max size for a serialized pool descriptor.

returns the maximum size that will be needed to hold a serialized pool descriptor.

Returns:

The maximum required size for a serialized pool descriptor.

dragonError_t dragon_memory_pool_serialize(dragonMemoryPoolSerial_t *pool_ser, const dragonMemoryPoolDescr_t *pool_descr)

Serialize a pool descriptor to be shared with other processes.

When sharing a pool, the pool descriptor may be serialized by the user to share with other processes which would use this to attach to the pool. Note that only local pools can be used to allocate memory. Non-local pool descriptors cannot be used for allocating memory on a separate node. Once the pool has been attached or the serialized data has been passed on to another process, it will be necessary to destroy the serialized pool descriptor since it contains malloced data.

Parameters:

• pool_ser – is a pointer to a structure that will hold the serialized pool descriptor.

• pool_descr – is the pool descriptor that is being serialized.

Returns:

DRAGON_SUCCESS or an error code.

dragonError_t dragon_memory_pool_serial_free(dragonMemoryPoolSerial_t *pool_ser)

Free the space used by a serialied pool descriptor.

When a pool descriptor is serialized, there is space that is malloced to hold the serialized pool descriptor. To prevent a memory leak in the current process, a serialized pool desctiptor should be destroyed once it is no longer needed, which might be after the process has attached to it.

Parameters:

pool_ser – is the serialized pool descriptor that should be cleaned up by freeing internal storage.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_attach(dragonMemoryPoolDescr_t *pool_descr, const dragonMemoryPoolSerial_t *pool_ser)

Attach to a pool using a serialied descriptor.

A process that is given a serialized pool descriptor can use it to attach to an existing pool by calling this function. Once the pool has been attached or the serialized data has been passed on to another process, it will be necessary to destroy the serialized pool descriptor since it contains malloced data.

Parameters:

• pool_descr – will be initialized if DRAGON_SUCCESS is returned.

• pool_ser – is the given serialized pool descriptor for this pool.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_attach_from_env(dragonMemoryPoolDescr_t *pool_descr, const char *env_var)

Given an environment variable name, use it to attach to a memory pool.

Certain environment variables contain serialized descriptors to resources, including memory pools created by Dragon’s run-time services. This function will attach to a pool descriptor whose serialized descriptor is found in an environment variable. Once a process no longer needs access to a memory pool, it should detach from it.

Parameters:

• pool_descr – is a pointer to a pool descriptor that will be initialized upon successful completion of this function.

• env_var – is a pointer to a null-terminated environment variable string which maps to a base64 encoded serialized memory pool descriptor.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_detach(dragonMemoryPoolDescr_t *pool_descr)

Detach from a memory pool.

Once a process no longer needs access to a memory pool, it should detach from it.

Parameters:

pool_descr – is the memory pool to detach from.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_descr_clone(dragonMemoryPoolDescr_t *newpool_descr, const dragonMemoryPoolDescr_t *oldpool_descr)

Make a copy of a memory pool descriptor.

Does a copy from oldpool_descr into newpool_descr providing a clone of the original.

Parameters:

• newpool_descr – is the newly cloned descriptor.

• oldpool_descr – is the original pool descriptor.

Returns:

DRAGON_SUCCESS or an error code.

Pool Information & Functionality

dragonError_t dragon_memory_pool_get_hostid(dragonMemoryPoolDescr_t *pool_descr, dragonULInt *hostid)

Get the hostid of the host where this pool resides.

The hostid of the pool can be used for identifying the location of this pool within the Dragon run-time nodes. It identifies the node where this pool exists.

Parameters:

• pool_descr – is a valid pool descriptor for the pool in question.

• hostid – is a pointer to the location where the hostid will be copied by this function call.

Returns:

DRAGON_SUCCESS or an error code.

dragonError_t dragon_memory_pool_get_uid_fname(const dragonMemoryPoolSerial_t *pool_ser, dragonULInt *uid_out, char **fname_out)

Get meta information about a memory pool.

Retrieve memory pool m_uid and optionally the filename of the pool without needing to attach to the pool. If m_uid is not NULL it will copy the m_uid of the pool into the space it points to. If filename is not NULL it will copy the filename of the pool using :c:func:strdup():. It is up to the caller to free the space filename points to in this case.

Parameters:

• m_uid – is a pointer to space where the m_uid can be copied or NULL if it is not needed.

• filename – is a pointer to a character pointer which will be initialized to point to to the pool’s filename unless NULL was provided in which case the filename copy is not performed.

Returns:

DRAGON_SUCCESS or error code

bool dragon_memory_pool_is_local(dragonMemoryPoolDescr_t *pool_descr)

Discover whether a pool is local or not.

Return true if the memory pool is on the current node and false, otherwise. Occassionally, it is necessary to know if a memory pool is local to a node when serialized descriptors are passed around.

Returns:

true if is is local and false otherwise.

dragonError_t dragon_memory_pool_allocations_free(dragonMemoryPoolAllocations_t *allocs)

dragonError_t dragon_memory_pool_allocation_exists(const dragonMemoryPoolDescr_t *pool_descr, const dragonMemoryAllocationType_t type, const dragonULInt type_id, int *flag)

Check whether a memory pool allocation exists.

Given the manifest information (type, type id) for a particular memory allocation in a pool, return true or false that the allocation exists via the flag argument. This method only works locally on the node where the memory pool exists. The process calling this function and the memory pool must be co-located on the same node.

Parameters:

• pool_descr – is the Memory Pool being queried.

• type – is an allocation type for the memory descriptor being queried.

• type_id – is the user supplied identifier for the memory descriptor being queried.

• flag – is a pointer to an integer where 1 will be stored if the memory exists and 0 otherwise.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_allocations(const dragonMemoryPoolDescr_t *pool_descr, dragonMemoryPoolAllocations_t *allocs)

Get all allocations from a memory pool.

This function returns all current allocations from the given memory pool. This function only works for pools that are co-located on the same node as the process calling this function.

Parameters:

• pool_descr – is a pointer to the descriptor to the memory pool.

• allocs – is a pointer to an allocations structure that will be initialized by this function.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_type_allocations(const dragonMemoryPoolDescr_t *pool_descr, const dragonMemoryAllocationType_t type, dragonMemoryPoolAllocations_t *allocs)

Get all allocations of a particular type from a memory pool.

This function returns all current allocations of a particular type from the given memory pool. This function only works for pools that are co-located on the same node as the process calling this function.

Parameters:

• pool_descr – is a pointer to the descriptor to the memory pool.

• type – is the type of the allocations to retrieve from the memory pool.

• allocs – is a pointer to an allocations structure that will be initialized by this function.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_allocations_destroy(dragonMemoryPoolAllocations_t *allocs)

Free local the allocations structure.

Calling this function frees internal mallocs that are done with the allocation sructure. This does not free the underlying memory allocations. This function should be called when the result of calling either of the get_allocations functions is no longer needed.

Parameters:

allocs – is the allocations structure that was returned from getting the allocations.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

Memory Lifecycle Management

dragonError_t dragon_memory_alloc(dragonMemoryDescr_t *mem_descr, const dragonMemoryPoolDescr_t *pool_descr, const size_t bytes)

Allocate memory from a pool.

This function allocates memory from a memory pool if the requested size is avialable. Otherwise, it returns a return code indicating that the requested size was not available.

Parameters:

• mem_descr – is a pointer to a memory descriptor that will be initialied by the call.

• pool_descr – is a pointer to a pool descriptor which will be used for the allocation.

• bytes – is the size of the requested allocation.

Returns:

DRAGON_SUCCESS or another dragonError_t return code. If the requested size is not then DRAGON_DYNHEAP_REQUESTED_SIZE_NOT_AVAILABLE is returned.

dragonError_t dragon_memory_alloc_blocking(dragonMemoryDescr_t *mem_descr, const dragonMemoryPoolDescr_t *pool_descr, const size_t bytes, const timespec_t *timer)

Allocate memory from a pool, waiting if necessary.

Allocates memory of the given size in bytes from a memory pool. The memory will be block aligned. The minimum block size of the pool determines its alignment. Pools are a finite sized resource. If the desired memory allocation size is not currently available, this call will block the current process for timeout until it is available. The effect of using this is that back pressure can be applied to a process or processes once they have consumed all the local resources they are allowed.

Parameters:

• mem_descr – is a pointer to the memory descriptor to be initialized.

• pool_descr – is a pointer to a pool descriptor for the pool in which to make the allocation.

• bytes – is the size of the requested allocation in bytes.

• timeout – a pointer to the timeout that is to be used. Providing NULL means to wait indefinitely. Providing a zero timeout (both seconds and nanoseconds) means to try once and not block if the space is not available.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_alloc_type(dragonMemoryDescr_t *mem_descr, const dragonMemoryPoolDescr_t *pool_descr, const size_t bytes, const dragonMemoryAllocationType_t type, const dragonULInt type_id)

Allocate memory from a pool.

Allocate memory for specific type with specific ID Use for allocating channels, channel buffers, and other non-general-purpose data allocations. Allocates memory of the given size in bytes from a memory pool. The memory will be block aligned. The minimum block size of the pool determines its alignment. Pools are a finite sized resource. If the desired memory allocation size is not currently available, this call will block the current process for timeout until it is available. The effect of using this is that back pressure can be applied to a process or processes once they have consumed all the local resources they are allowed.

Parameters:

• mem_descr – is a pointer to the memory descriptor to be initialized.

• pool_descr – is a pointer to a pool descriptor for the pool in which to make the allocation.

• bytes – is the size of the requested allocation in bytes.

• type – is constant value associated with the type of memory to be allocated.

• type_id – is a user supplied value to identify the memory allocation of this given type.

Returns:

DRAGON_SUCCESS or another dragonError_t return code. If the requested size is not then DRAGON_DYNHEAP_REQUESTED_SIZE_NOT_AVAILABLE is returned.

dragonError_t dragon_memory_alloc_type_blocking(dragonMemoryDescr_t *mem_descr, const dragonMemoryPoolDescr_t *pool_descr, const size_t bytes, const dragonMemoryAllocationType_t type, const dragonULInt type_id, const timespec_t *timer)

Allocate memory from a pool, waiting if necessary.

Allocate memory for specific type with specific ID Use for allocating channels, channel buffers, and other non-general-purpose data allocations. Allocates memory of the given size in bytes from a memory pool. The memory will be block aligned. The minimum block size of the pool determines its alignment. Pools are a finite sized resource. If the desired memory allocation size is not currently available, this call will block the current process for timeout until it is available. The effect of using this is that back pressure can be applied to a process or processes once they have consumed all the local resources they are allowed.

Parameters:

• mem_descr – is a pointer to the memory descriptor to be initialized.

• pool_descr – is a pointer to a pool descriptor for the pool in which to make the allocation.

• bytes – is the size of the requested allocation in bytes.

• type – is constant value associated with the type of memory to be allocated.

• type_id – is a user supplied value to identify the memory allocation of this given type.

• timeout – a pointer to the timeout that is to be used. Providing NULL means to wait indefinitely. Providing a zero timeout (both seconds and nanoseconds) means to try once and not block if the space is not available.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

size_t dragon_memory_max_serialized_len()

Get the maximum length of a serialized memory descriptor.

Memory allocations may be serialized and shared with other processes. In some situations it may be necessary to preallocate some space to be used to store this serialized data. This function returns the maximum amount of space that would be required in bytes.

Returns:

the size in bytes that is needed for the maximum sized serialized descriptor.

dragonError_t dragon_memory_serialize(dragonMemorySerial_t *mem_ser, const dragonMemoryDescr_t *mem_descr)

Serialize a memory descriptor.

Memory descriptors, allocated from memory pools, may be serialized to share with other processes. This function returns a serialized descriptor for the memory allocation.

Parameters:

• mem_ser – is a pointer to a serialized memory descriptor structure.

• mem_descr – is the memory descriptor being serialized.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_attach(dragonMemoryDescr_t *mem_descr, const dragonMemorySerial_t *mem_ser)

Attach to an existing memory allocation.

A serialized memory descriptor, provided from another process, is attached to the current process by making this call. Upon successful completion, the memory descriptor is initialized. Not that you can attach to remote, non-local memory descriptors but you cannot get a pointer into a non-local memory allocation.

Parameters:

• mem_descr – is initialized after this call.

• mem_ser – is the serialized memory descriptor provided to this process.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_detach(dragonMemoryDescr_t *mem_descr)

Detach from a memory allocation.

Once a memory allocation is no longer needed, a process can either detach from it or destroy it. Detach leaves the memory allocation in existence, but cleans up any process local references to it.

Parameters:

mem_descr – is the memory descriptor to be detached.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_serial_free(dragonMemorySerial_t *mem_ser)

Free the serialized descriptor.

A serialized memory descriptor, created with the serialize function call, will contain malloced space that will need to be freed when the serialized descriptor is no longer needed by the current process. At that time it can be freed. This would be after it has passed the serialized descriptor to a new process or when it is longer being used in the current process.

Parameters:

mem_ser – is a pointer to the serialized memory descriptor to free. The descriptor itself is not freed, but its internal structures are freed if needed.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_get_alloc_memdescr(dragonMemoryDescr_t *mem_descr, const dragonMemoryPoolDescr_t *pool_descr, const dragonMemoryAllocationType_t type, const dragonULInt type_id, const dragonULInt offset, const dragonULInt *bytes_size)

Get a memory descriptor from it (type, type id) identifier.

Given a (type, type id) pair for a given pool, the manifest is used to find the identified memory descriptor and return it. This only works on the node where the pool actually resides. It does not work off-node. A clone of the memory descriptor is intialized by this call.

Parameters:

• mem_descr – is the memory descriptor to initialize with the located memory.

• pool_descr – is the memory pool that is being queried.

• type – is the type part of the memory descriptor identifier

• type_id – is the id part of the memory descriptor identifier

• offset – is an offset into the memory descriptor used to provide a cloned offset into the returned memory descriptor.

• bytes_size – is a pointer to an unsigned integer where the size of the memory descriptor clone is stored.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

Memory Information & Functionality

dragonError_t dragon_memory_get_size(const dragonMemoryDescr_t *mem_descr, size_t *bytes)

Get a memory descriptor size.

This function returns the size of the given memory descriptor. If this is an original memory descriptor and not a clone, then the original requested size will be returned. If it is a clone, it will be the size minus whatever offset was provided when the clone was made. This function works both on-node and off-node.

Parameters:

• mem_descr – is a pointer to a valid, initialized memory descriptor

• bytes – is a pointer to where to store the number of bytes for the given memory descriptor.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_get_pool(const dragonMemoryDescr_t *mem_descr, dragonMemoryPoolDescr_t *pool_descr)

Get the pool where this memory descriptor resides.

Get the pool where this memory descriptor resides. This can be called both on-node and off-node.

Parameters:

• mem_descr – is a pointer to a valid memory descriptor.

• pool_descr – is a pointer to a pool descriptor which will be initialized by this call.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_get_pointer(const dragonMemoryDescr_t *mem_descr, void **ptr)

Get a pointer into a memory descriptor.

Calling this function gives the caller a pointer into a memory allocation starting at offset 0 if it is the original memory descriptor or at the cloned offset if this is a clone. This function only works on the node where the memory descriptor’s pool resides.

Parameters:

• mem_descr – is a pointer to a memory descriptor into which a pointer is returned.

• ptr – is a pointer to a pointer where the pointer into the memory descriptor is copied.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_free(dragonMemoryDescr_t *mem_descr)

Free a memory allocation.

Call this to free a memory allocation in a pool. Once done, all pointers into the memory allocation are invalid and should not be used again. Doing so would have unpredictable results. Calling this on a clone of a memory descriptor will result in all the memory in the allocation being freed, not just the cloned region. This operation only works when the memory descriptor is local to the node where the process calling it is running.

Parameters:

mem_descr – is the memory descriptor to free.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_descr_clone(dragonMemoryDescr_t *newmem_descr, const dragonMemoryDescr_t *oldmem_descr, ptrdiff_t offset, size_t *custom_length)

Clone a memory descriptor with a custom offset.

Given a memory descriptor, construct a clone with a new offset and possible new length.

Parameters:

• newmem_descr – is the memory descriptor to hold the clone.

• oldmem_descr – is the memory descriptor from which the clone is made.

• offset – is the new offset to be used into the oldmem_descr.

• custom_length – is a pointer to the new length to be used for the clone which is useful when you want to carve up a larger allocation. Providing NULL will use the original length minus the offset.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_modify_size(dragonMemoryDescr_t *mem_descr, const size_t new_size, const timespec_t *timeout)

Change the size of a given memory descriptor.

Without making a clone, change the size of a given memory descriptor.

Parameters:

• mem_descr – is the memory descriptor to modify.

• new_size – is the new size. The new size cannot cause the memory descriptor to go beyond the original allocation’s size unless it is a zero-byte allocation in which case a new allocation is made which will be big enough to hold the given size.

• timeout – is the timeout to use when a zero-byte allocation has its size modified to a non-zero byte allocation. Otherwise not used.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.