SHMEM_MALLOC(3)

💖 NAME 💖

okay so bestie, welcome to Open MPI's page SHMEM_MALLOC(3) — the ✨ symmetric heap memory management functions ✨, starring the whole girl group: shmem_malloc(3), shmem_free(3), shmem_align(3), shmem_realloc(3) and their aliases shmalloc(3), shfree(3), shmemalign(3), shrealloc(3). they all do memory stuff together, symmetrically, as a treat 🫶

---

🌸 SYNOPSIS 🌸

C or C++, periodt:

#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 🦋

okay so shmem_malloc</p> hands you back a pointer to a block of at least size bytes, suitably aligned for any use. and here's the ✨ twist ✨ — that space comes out of the symmetric heap, not the private heap like your regular malloc(3) does. different heap, different vibe 💅

shmem_align</p> is the glow-up version: it allocates a block in the symmetric heap that has a byte alignment specified by the alignment argument. alignment? we love her.

shmem_free</p> makes the block that ptr points to get deallocated, i.e. made available for further allocation. if ptr is a null pointer, literally nothing happens, no action, we move on. otherwise — if the argument doesn't match a pointer that a symmetric heap function returned earlier, or if that space has already been deallocated — then malloc_error gets set to indicate the error, and shfree returns. so like. track your pointers, bestie 😭

shmem_realloc</p> changes the size of the block that ptr points to, to the size (in bytes) specified by size. the contents of the block stay 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 (mystery bytes, no cap 👀). if ptr is a null pointer, shrealloc behaves like the shmalloc function 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 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. and if the space cannot be allocated, the block that ptr points to is left unchanged.

shmem_malloc</p>, shmem_free</p> and shmem_realloc</p> exist so that multiple PEs in an application can allocate symmetric, remotely accessible memory blocks 🫶. those blocks can then be used with (shmem) communication routines. and here's the main character detail: each of these functions calls the shmem_barrier_all(3) function before returning — that way all PEs participate in the memory allocation, and the memory on other PEs can be used as soon as the local PE returns. iconic behaviour, honestly.

⚠️ and you, yes you, are responsible for calling these functions with identical argument(s) on all PEs. if you use differing size arguments, subsequent calls may not return the same symmetric heap address on all PEs. fr fr, keep it symmetric or suffer 💀

---

🎀 NOTES 🎀

the total size of the symmetric heap is determined at job startup — not vibes-based, sorry. you can adjust the size of the heap using the SHMEM_SYMMETRIC_HEAP_SIZE environment variable 🌈. peep the intro_shmem(3) man page for further details. also!! shmem_malloc, shmem_free and shmem_realloc differ from the private heap allocation functions in one big way: all PEs in an application must call them (a barrier is used to ensure this). group project energy, everybody participates 🙈

---

👑 RETURN VALUES 👑

• shmem_malloc</p> returns a pointer to the allocated space — which should be identical on all PEs 💖 — otherwise it returns a null pointer (with malloc_error set).
• shmem_free</p> returns no value. nothing. silence. she gives nothing and that's fine.
• shmem_realloc</p> 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(3)
• shmem_init(3)

---

Copyright

2003-2026, The Open MPI Community 💜

---

and that's the whole page, bestie — go allocate symmetrically, slay, and remember: barrier first, questions later. this was SHMEM_MALLOC(3) from the Open MPI manual, dated Sep 10, 2026 🌸✨💅