oracular (3) shmalloc.openmpi.3.gz

NAME

       shmalloc(3), shfree(3), shmemalign(3), shrealloc(3) - Symmetric heap memory management functions.

SYNOPSIS

       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;

DESCRIPTION

       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.

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

RETURN VALUES

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

SEE ALSO

       intro_shmem(3), my_pe(3I), start_pes(3)