.\" Man page generated from reStructuredText.
.
.TH "SHMALLOC" "3" "Jul 22, 2024" "" "Open MPI"
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
\fIshmalloc\fP(3), \fIshfree\fP(3), \fIshmemalign\fP(3), \fIshrealloc\fP(3) \-
Symmetric heap memory management functions.
.SH SYNOPSIS
.sp
C or C++:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft 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
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The \fBshmalloc\fP 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 \fImalloc\fP(3), which allocates from the
private heap).
.sp
The \fBshmemalign\fP function allocates a block in the symmetric heap that
has a byte alignment specified by the alignment argument.
.sp
The \fBshfree\fP 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.
.sp
The \fBshrealloc\fP function changes the size of the block to which ptr
points to, to the size (in bytes) specified by size.
.sp
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.
.sp
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
\fI\%shmem_barrier_all\fP(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.
.sp
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.
.SH NOTES
.sp
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 \fIintro_shmem\fP(3) man page for further
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).
.SH RETURN VALUES
.sp
The \fBshmalloc\fP 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 \fBshfree\fP function returns no
value. The \fBshrealloc\fP function returns a pointer to the allocated
space (which may have moved); otherwise, it returns a null pointer (with
malloc_error set).
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIintro_shmem\fP(3) \fImy_pe\fP(3) \fIstart_pes\fP(3)
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2003-2024, The Open MPI Community
.\" Generated by docutils manpage writer.
.