Memory Management#
Intel® SHMEM provides a set of APIs for managing the symmetric heap. The APIs allow one to dynamically allocate, deallocate, and align symmetric data objects in the symmetric heap.
The ishmem_malloc, ishmem_align, and ishmem_free routines are
provided so that multiple PEs in a program can allocate symmetric, remotely
accessible memory blocks.
These memory blocks can then be used with ishmem communication routines.
The symmetric memory allocation routines must be called by all PEs in the
world team.
When no action is performed, these routines return without performing a
barrier.
Otherwise, each of these routines includes at least one call to a procedure
that is semantically equivalent to ishmem_barrier_all:
ishmem_malloc and ishmem_align call a barrier on exit;
and ishmem_free calls a barrier on entry.
This ensures that all PEs participate in the memory allocation, and that the
memory on other PEs can be used as soon as the local PE returns.
The user is responsible for calling these routines with identical argument(s)
on all PEs; if differing ptr, size, or alignment arguments are
used, the behavior of the call and any subsequent ishmem calls is
undefined.
ISHMEM_MALLOC#
-
void *ishmem_malloc(size_t size)#
- Parameters:
size – The size, in bytes, of a block to be allocated from the symmetric heap.
- Returns:
The symmetric address of the allocated space; otherwise, it returns a null pointer.
Callable from the host.
Description:
The ishmem_malloc routine is a collective operation on the world team that
returns the symmetric address of a block of at least size bytes, which
shall be suitably aligned so that it may be assigned to a pointer to any type
of object.
This space is allocated from the symmetric heap (in contrast to malloc, which
allocates from the private heap).
The memory space is uninitialized.
When size is zero, the ishmem_malloc routine performs no action and
returns a null pointer; otherwise, ishmem_malloc calls a barrier on exit.
The value of the size argument must be identical on all PEs; otherwise, the behavior is undefined.
ISHMEM_FREE#
-
void ishmem_free(void *ptr)#
- Parameters:
ptr – Symmetric address of an object in the symmetric heap.
- Returns:
None.
Callable from the host.
Description:
The ishmem_free routine is a collective operation on the world team that
causes the block to which ptr points to be deallocated, that is, made
available for further allocation.
If ptr is a null pointer, no action is performed; otherwise,
ishmem_free calls a barrier on entry.
It is the user’s responsibility to ensure that no communication operations
involving the given memory block are pending on other communication contexts
prior to calling ishmem_free.
The value of the ptr argument must be identical on all PEs; otherwise, the behavior is undefined.
ISHMEM_ALIGN#
-
void ishmem_align(size_t alignment, size_t size)#
- Parameters:
alignment – Byte alignment of the block allocated on the symmetric heap.
size – The size, in bytes, of a block to be allocated from the symmetric heap.
- Returns:
An aligned symmetric address whose value is a multiple of alignment; otherwise returns a null pointer.
Callable from the host.
Description
The ishmem_align routine is a collective operation on the world team that
allocates a block in the symmetric heap that has a byte alignment specified by
the alignment argument.
The value of alignment shall be a multiple of sizeof(void *) that is
also a power of two.
Otherwise, the behavior is undefined. When size is zero, the ishmem_align
routine performs no action and returns a null pointer; otherwise,
ishmem_align call a barrier on exit.
The memory space is uninitialized.
ISHMEM_CALLOC#
-
void *ishmem_calloc(size_t count, size_t size)#
- Parameters:
count – The number of elements to allocate.
size – The size in bytes of each element to allocate.
- Returns:
A pointer to the lowest byte address of the allocated space; otherwise, it returns a null pointer.
Callable from the host.
- Description:
The
ishmem_callocroutine is a collective operation on the world team that allocates a region of remotely-accessible memory for an array of count objects of size bytes each and returns a pointer to the lowest byte address of the allocated symmetric memory. The space is initialized to all bits zero.If the allocation succeeds, the pointer returned shall be suitably aligned so that it may be assigned to a pointer to any type of object. If the allocation does not succeed, or either count or size is 0, the return value is a null pointer.
The values for count and size shall each be equal across all PEs calling
ishmem_calloc; otherwise, the behavior is undefined.When count or size is 0, the
ishmem_callocroutine returns without performing a barrier. Otherwise, this routine calls a procedure that is semantically equivalent to a barrier on exit.