Managed Memory

Description

Dragon Managed Memory Pools are created to, as the name indicates, manage shared memory allocations between processes. When a pool is created, the user decides on the size of the pool. Then the user may make allocations from the pool and serialize and share those allocations with other on-node processes. Typically this is done using other higher-level objects like channels or even higher level objects built on channels like queues, or the Distributed Dictionary, both of which also support off-node communication and synchronization via a Dragon transport agent.

Constants

enum dragonMemoryPoolType_t

The type of memory pool.

The type of the memory pool. SHM, HUGEPAGE, and GPU are the types currently support. FILE and PRIVATE are for possible future use.

Values:

enumerator DRAGON_MEMORY_TYPE_SHM

enumerator DRAGON_MEMORY_TYPE_HUGEPAGE

enumerator DRAGON_MEMORY_TYPE_GPU

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

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.

enumerator DRAGON_MEMORY_ALLOC_BOOTSTRAP

Structures

struct dragonMemoryPoolAttr_t

#include <managed_memory.h>

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 free_space

Free space in the pool in bytes. Read-only.

double utilization_pct

Free space as a percentage of total space of the pool. Read-only.

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 max_allocations

The maximum number of concurrent allocations among all processes. This number is set to 1048576 entries (1024^2 entries) or the number of segments in the pool, whichever is smaller. This can be set by the user to something bigger if needed.

size_t waiters_for_manifest

Read-only. At the time of the call, this is the number of processes that are awaiting a manifest table entry because the manifest is currently full. Read-only.

size_t manifest_entries

Read-only. This is the number of entries of the total max_allocations that are currently in use. If there are waiters, then manifest_entries should equal max_allocations. Read-only.

size_t max_manifest_entries

The maximum concurrently used manifest locations of the pool since pool creation. Read-only.

size_t manifest_allocated_size

The size in bytes of the manifest. Read-only.

size_t manifest_table_size

The size in bytes of the internal allocation table. Read-only.

size_t manifest_heap_size

The size in bytes of the internal heap manager. Read-only.

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

#include <managed_memory.h>

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.

struct dragonMemoryDescr_t

#include <managed_memory.h>

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

#include <managed_memory.h>

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

#include <managed_memory.h>

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

#include <managed_memory.h>

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.

struct dragonHeapStatsAllocationItem_t

#include <managed_memory.h>

The number of free memory blocks with the memory size.

dyn_mem stats provide statistics for the heap. This struture is returned as an array for the free blocks of each block size. The array starts at 0 and runs to the number of block sizes - 1. Each item of the array contains the items given here.

Public Members

size_t block_size

The size of the block for which this free blocks applies.

size_t num_blocks

The number of blocks of this size that are free.

Pool Lifecycle Management

dragonError_t dragon_memory_attr_init(dragonMemoryPoolAttr_t *attr)

Initialize 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_get_attr(dragonMemoryPoolDescr_t *pool_descr, dragonMemoryPoolAttr_t *attr)

dragonError_t dragon_memory_pool_create(dragonMemoryPoolDescr_t *pool_descr, const 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_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_attach_default(dragonMemoryPoolDescr_t *pool)

Attach to Default Pool.

Processes created by Dragon have access to a default pool, one per node. The default pool on a node can be used when no other managed memory pools are available or have been provided. This function attaches to the default pool on its current node.

Parameters:

pool – is a pointer to a pool descriptor to be initialized by this call.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

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

Pool Information & Functionality

dragonError_t dragon_memory_pool_process_local_register_with_gpu(dragonMemoryPoolDescr_t *pool_descr)

Register the pool with a GPU from the current process.

Registers the memory pool with the GPU so that it is pinned and allows for faster memcpys between the host and a GPU device.

Parameters:

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

Returns:

DRAGON_SUCCESS or an error code.

dragonError_t dragon_memory_pool_process_local_unregister_with_gpu(dragonMemoryPoolDescr_t *pool_descr)

Unregister the pool with a GPU from the current process.

Unregisters a memory pool that was previously registered.

Parameters:

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

Returns:

DRAGON_SUCCESS or an error code.

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_runtime_is_local(dragonMemoryPoolDescr_t *pool_descr, bool *runtime_is_local)

Determine if a pool is hosted in the local runtime.

Parameters:

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

• runtime_is_local – is a boolean indicating if the pool is hosted in the local runtime.

Returns:

DRAGON_SUCCESS or an error code.

dragonError_t dragon_memory_pool_get_rt_uid(dragonMemoryPoolDescr_t *pool_descr, dragonRT_UID_t *rt_uid)

Get the runtime unique id (rt_uid) for a pool.

Parameters:

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

• rt_uid – is the unique value used to identify a runtime. The value is composed of two IP addresses: the internet IP address of the login node of the system hosting the runtime, and the intranet IP address of the head node for the runtime.

Returns:

DRAGON_SUCCESS or an error code.

dragonError_t dragon_memory_pool_get_uid_fname(const dragonMemoryPoolSerial_t *pool_ser, dragonULInt *m_uid, char **filename)

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

dragonError_t dragon_memory_pool_muid(dragonMemoryPoolDescr_t *pool_descr, dragonULInt *muid)

Get the muid from a pool.

Especially when attaching a pool, the muid isn’t always known apriori. This call can be used to discover the muid of any pool.

Parameters:

• pool – is a pool descriptor

• muid – is a pointer to space to receive the muid

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_free_size(dragonMemoryPoolDescr_t *pool_descr, uint64_t *free_size)

Get the free space in the pool.

Return the amount of free space.

Parameters:

• pool – is a pool descriptor

• free_size – is a pointer to space to receive the free size in bytes.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_total_size(dragonMemoryPoolDescr_t *pool_descr, uint64_t *total_size)

Get the total space for the pool.

Return the amount of space for the whole pool, whether currently allocated or not.

Parameters:

• pool – is a pool descriptor

• free_size – is a pointer to space to receive the total size in bytes.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_utilization_pct(dragonMemoryPoolDescr_t *pool_descr, double *utilization_pct)

Get the free utilization percent in the pool.

Return the percentage of free space.

Parameters:

• pool – is a pool descriptor

• utilization_pct – is a pointer to space to receive the pool usage in percentage.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_free_blocks(dragonMemoryPoolDescr_t *pool_descr, dragonHeapStatsAllocationItem_t *free_blocks)

Get the number of free blocks with particular block_size in the pool.

Return the percentage of free space.

Parameters:

• pool – is a pool descriptor

• free_blocks – is a pointer to space to receive the number of free blocks with different block sizes as an array of dragonHeapStatsAllocationItem_t.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_num_block_sizes(dragonMemoryPoolDescr_t *pool_descr, size_t *num_block_sizes)

Get the number of free blocks with particular block_size in the pool.

Return the percentage of free space.

Parameters:

• pool – is a pool descriptor

• num_block_sizes – is a pointer to space to receive the number of block sizes as a size_t value.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

Memory Lifecycle Management

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_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_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_id(dragonMemoryDescr_t *mem_descr, uint64_t *id)

Get the unique id for this memory descriptor in its pool.

This function retrieves the identifier assigned to this memory allocation. It is unique for this instance of its pool only. It is unique for this memory allocation in its pool.

Parameters:

• mem_descr – The given memory descriptor

• id – The memory allocation’s unique identifier

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_from_id(const dragonMemoryPoolDescr_t *pool_descr, uint64_t id, dragonMemoryDescr_t *mem_descr)

Get the the memory descriptor associated with a pool given its unique id.

This function initializes a memory descriptor given its unique id in a pool.

Parameters:

• pool_descr – The pool in which to look for the memory.

• id – The memory allocation’s unique identifier

• mem_descr – The memory descriptor to be initialized.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

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

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(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_type_blocking(dragonMemoryDescr_t *mem_descr, const dragonMemoryPoolDescr_t *pool_descr, const size_t bytes, const dragonMemoryAllocationType_t type, const timespec_t *timeout)

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.

• 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)

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.

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

Memory Information & Functionality

dragonError_t dragon_memory_pool_allocation_exists(dragonMemoryDescr_t *mem_descr, int *flag)

Check whether a memory pool allocation exists.

Given a memory descriptor 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. This method checks to see if memory was deleted after being attached.

Parameters:

• mem_descr – is a user supplied memory descriptor 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_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.

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_get_pointer(const dragonMemoryPoolDescr_t *pool_descr, void **base_ptr)

Get the base address for a memory pool.

This function returns the base address for a memory pool.

Parameters:

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

• base_ptr – is a pointer to the returned base address.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_pool_get_size(const dragonMemoryPoolDescr_t *pool_descr, size_t *size)

Get the total size of a memory pool.

This function returns the total size of a memory pool.

Parameters:

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

• size – is a pointer to the returned size of the pool.

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_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_alloc_memdescr(dragonMemoryDescr_t *mem_descr, const dragonMemoryPoolDescr_t *pool_descr, const dragonULInt 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.

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

dragonError_t dragon_memory_get_ptr_info(const dragonMemoryDescr_t *mem_descr, void **ptr, size_t *size)

Get the virtual address and size of the buffer associated with a memory descriptor.

Get the virtual address and size of the buffer associated with the memory descriptor.

Parameters:

• mem_descr – is the memory descriptor.

• ptr – is a double pointer to update with the virtual address of the underlying buffer.

• size – is a pointer to update with the size in bytes of the underlying buffer.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

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.

dragonError_t dragon_memory_hash(dragonMemoryDescr_t *mem_descr, dragonULInt *hash_value)

Compute a hash value for a memory allocation.

Use the Dragon hash function to compute a hash value

Parameters:

• mem_descr – is the memory descriptor to hash.

• hash_value – is the hash function’s value

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_equal(dragonMemoryDescr_t *mem_descr1, dragonMemoryDescr_t *mem_descr2, bool *result)

Check for equal contents.

Check that two memory allocations have equal contents.

Parameters:

• mem_descr1 – One memory allocation.

• mem_descr2 – Other memory allocation.

• result – is true if equal and false otherwise.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_is(dragonMemoryDescr_t *mem_descr1, dragonMemoryDescr_t *mem_descr2, bool *result)

Check for to memory allocations are actually the same.

Check that two memory allocations are the same allocation.

Parameters:

• mem_descr1 – One memory allocation.

• mem_descr2 – Other memory allocation.

• result – is true if equal and false otherwise.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_copy_size(dragonMemoryDescr_t *from_mem, dragonMemoryDescr_t *to_mem, size_t size)

Copy a specific size of data between memory allocations.

Copy between memory allocations. The size to copy is provided.

Parameters:

• from_mem – Memory allocation to copy data from.

• to_mem – Memory allocation to copy data to.

• size – Number of bytes to copy from from_mem to to_mem.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_copy(dragonMemoryDescr_t *from_mem, dragonMemoryDescr_t *to_mem)

Copy an entire memory allocation to another memory allocation.

Copy between memory allocations.

Parameters:

• from_mem – Memory allocation to copy data from.

• to_mem – Memory allocation to copy data to.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_copy_to_pool(dragonMemoryDescr_t *from_mem, dragonMemoryDescr_t *to_mem, dragonMemoryPoolDescr_t *to_pool, const timespec_t *timeout)

Copy an entire memory allocation to another memory allocation.

Copy between memory allocations.

Parameters:

• from_mem – Memory allocation to copy data from.

• to_pool – Memory pool to copy data to.

• timeout – is the timeout to use when waiting for memory to become available.

• to_mem – Memory allocation from to_pool that data is copied to.

Returns:

DRAGON_SUCCESS or another dragonError_t return code.

dragonError_t dragon_memory_clear(dragonMemoryDescr_t *mem_descr, size_t start, size_t stop)