|
« Return to documentation listing
Table of Contents
shmalloc(3), shfree(3), shmemalign(3), shrealloc(3) - Symmetric
heap memory management functions.
C or C++:
#include <mpp/shmem.h>
void *shmalloc(size_t size);
void shfree(void *ptr);
void *shrealloc(void *ptr, size_t size);
void *shmemalign(size_t alignment, size_t size);
extern long malloc_error;
The shmalloc function 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(3C), which allocates from the private
heap).
The shmemalign function allocates a block in the symmetric heap that
has a byte alignment specified by the alignment argument.
The shfree function
causes the block to which ptr points to, to be deallocated, that is, made
available for further allocation. If ptr is a null pointer, no action occurs;
otherwise, if the argument does not match a pointer earlier returned by
a symmetric heap function, or if the space has already been deallocated,
malloc_error is set to indicate the error, and shfree returns.
The shrealloc
function changes the size of the block to which ptr points to, 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 value
of the newly allocated portion of the block is indeterminate. If ptr is
a null pointer, the shrealloc function behaves like the shmalloc function
for the specified size. If size is 0 and ptr is not a null pointer, the
block to which it points to is freed. Otherwise, if ptr does not match a
pointer earlier returned by a symmetric heap function, or if the space
has already been deallocated, the malloc_error variable is set to indicate
the error, and shrealloc returns a null pointer. If the space cannot be
allocated, the block to which ptr points to is unchanged.
The shmalloc,
shfree, and shrealloc functions are provided so that multiple PEs in an
application can allocate symmetric, remotely accessible memory blocks. These
memory blocks can then be used with (shmem) communication routines. Each
of these functions call the shmem_barrier_all(3) function before returning;
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 functions with identical argument(s)
on all PEs; if differing size arguments are used, subsequent calls may
not return the same symmetric heap address on all PEs.
The total size
of the symmetric heap is determined at job startup. One can adjust the size
of the heap using the SHMEM_SYMMETRIC_HEAP_SIZE environment variable. See
the intro_shmem(3) man page for futher details. The shmalloc, shfree, and
shrealloc functions differ from the private heap allocation functions in
that all PEs in an application must call them (a barrier is used to ensure
this).
The shmalloc function returns a pointer to the allocated
space (which should be identical on all PEs); otherwise, it returns a null
pointer (with malloc_error set). The shfree function returns no value. The
shrealloc function returns a pointer to the allocated space (which may
have moved); otherwise, it returns a null pointer (with malloc_error set).
intro_shmem(3), my_pe(3I), start_pes(3)
Table of Contents
« Return to documentation listing
|
