SHMEM_REALLOC(3)

💅 SHMEM_REALLOC 💅 — Open MPI, section 3 of the manual, bestie

okay so this whole page is about symmetric heap memory management and it's actually about a whole lil friend group of functions, not just one:

• shmem_malloc
• shmem_free
• shmem_align
• shmem_realloc
• shmalloc
• shfree
• shmemalign
• shrealloc

like, they all showed up to the same party, so we're covering all of them. 🎀

---

✨ 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 🌸

shmem_malloc hands you back a pointer to a block of at least size bytes, and it's suitably aligned for any use. The tea here: this space comes out of the symmetric heap, not the private heap like malloc(3) does. different heap, different vibe. 🦋

shmem_align allocates a block in the symmetric heap that has a byte alignment specified by the alignment argument. slay.

shmem_free deallocates the block that ptr points to — aka it makes that memory available for further allocation. now, the fine print, and it matters:

• If ptr is a null pointer, no action occurs.
• Otherwise, if the argument doesn't match a pointer that a symmetric heap function returned earlier, or if the space has already been deallocated, then malloc_error is set to indicate the error, and shfree returns. 💀

shmem_realloc changes the size of the block that ptr points to, to the size (in bytes) you specify.

The contents of the block stay unchanged up to the lesser of the new and old sizes. If the new size is bigger, the value of the newly allocated portion of the block is indeterminate — like, nobody knows, it's a mystery, don't count on it. If ptr is a null pointer, shrealloc behaves just like shmalloc for the specified size. If size is 0 and ptr is not a null pointer, the block it points to is freed. Otherwise — if ptr doesn't match a pointer a symmetric heap function returned earlier, or if the space has already been deallocated — the malloc_error variable is set to indicate the error, and shrealloc returns a null pointer. And if the space can't be allocated at all, the block that ptr points to is unchanged. 🫶

shmem_malloc, shmem_free, and shmem_realloc exist so that multiple PEs in one application can allocate symmetric, remotely accessible memory blocks. Those blocks can then be used with (shmem) communication routines. And here's the iconic part: every one of these functions calls shmem_barrier_all before returning 😭 — that's what makes sure all PEs participate in the memory allocation, and that the memory on other PEs can be used as soon as the local PE returns. teamwork, fr fr.

⚠️ The user is responsible for calling these functions with identical argument(s) on all PEs. If differing size arguments get used, subsequent calls may not return the same symmetric heap address on all PEs. no cap.

---

🫶 NOTES 🫶

The total size of the symmetric heap is determined at job startup. You can adjust the size of the heap with the SHMEM_SYMMETRIC_HEAP_SIZE environment variable. Peep the intro_shmem(3) man page for further details. 👑

shmem_malloc, shmem_free, and shmem_realloc are different from the private heap allocation functions because all PEs in an application must call them — a barrier is used to ensure this. it's giving main character energy, mandatory attendance.

---

👑 RETURN VALUES 👑

• shmem_malloc returns a pointer to the allocated space — and that pointer should be identical on all PEs ✨ — otherwise it returns a null pointer (with malloc_error set).
• shmem_free returns no value. it just does its thing and leaves.
• shmem_realloc returns a pointer to the allocated space (which may have moved, so don't get attached) — otherwise it returns a null pointer (with malloc_error set).

See also

• intro_shmem(3)
• shmem_my_pe(3)
• shmem_init(3)

---

🌈 COPYRIGHT 🌈

2003-2026, The Open MPI Community

---

and that's the whole page bestie 💖 this lovely lil man page dropped on Sep 10, 2026, brought to you by the Open MPI girlies — go call your barriers, stay symmetric, and don't leak. mwah 🎀🦋✨