NAME

       shmem_malloc(3),  shmem_free(3),  shmem_align(3), shmem_realloc(3) shmalloc(3), shfree(3),
       shmemalign(3), shrealloc(3) - Symmetric heap memory management functions.

SYNOPSIS

       C or C++:
       #include <mpp/shmem.h>

       void *shmem_malloc(size_t size);
       void *shmalloc(size_t size);

       void shmem_free(void *ptr);
       void shfree(void *ptr);

       void *shmem_realloc(void *ptr, size_t size);
       void *shrealloc(void *ptr, size_t size);

       void *shmem_align(size_t alignment, size_t size);
       void *shmemalign(size_t alignment, size_t size);

       extern long malloc_error;

DESCRIPTION

       The shmem_malloc 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 shmem_align function allocates a block in the symmetric heap that has a byte alignment
       specified by the alignment argument.

       The  shmem_free  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  shmem_realloc  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  shmem_malloc,  shmem_free,  and shmem_realloc 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.

NOTES

       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   shmem_malloc,   shmem_free,   and
       shmem_realloc  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).

RETURN VALUES

       The shmem_malloc 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
       shmem_free function returns no value.  The shmem_realloc function returns a pointer to the
       allocated  space  (which  may  have  moved);  otherwise,  it  returns a null pointer (with
       malloc_error set).

SEE ALSO

       intro_shmem(3), shmem_my_pe(3I), shmem_init(3)