The shmem_malloc, shmem_free, shmem_realloc, and shmem_align routines are
collective operations that require participation by all PEs.
The shmem_malloc routine returns a pointer to a block of at least
size bytes suitably aligned for any use. This space is allocated from the
symmetric heap (in contrast to malloc, which allocates from the private
heap).
The shmem_align routine allocates a block in the symmetric heap that has
a byte alignment specified by the alignment argument.
The shmem_free routine 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 occurs.
The shmem_realloc routine changes the size of the block to which
ptr points to the size (in bytes) specified by size. The contents
of the block are unchanged up to the lesser of the new and old sizes. If the
new size is larger, the newly allocated portion of the block is
uninitialized. If ptr is a null pointer, the shmem_realloc routine behaves
like the shmem_malloc routine for the specified size. If size is 0 and ptr
is not a null pointer, the block to which it points is freed. If the space
cannot be allocated, the block to which ptr points is unchanged.
The shmem_malloc, shmem_align, shmem_free, and shmem_realloc 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
OpenSHMEM communication routines. Each of these routines includes at least one
call to a procedure that is semantically equivalent to shmem_barrier_all:
shmem_malloc and shmem_align call a barrier on exit; shmem_free calls a
barrier on entry; and shmem_realloc may call barriers on both entry and exit,
depending on whether an existing allocation is modified and whether new
memory is allocated. 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 implicit barriers performed by these routines quiet the
default context. It is the user's responsibility to ensure that no
communication operations involving the given memory block are pending on
other contexts prior to calling the shmem_free and shmem_realloc routines.
The user is also 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 OpenSHMEM calls is undefined.