SHREALLOC(3)

🎀 NAME 🎀

okay bestie, welcome to the symmetric heap ✨ this page covers shmem_malloc(3), shmem_free(3), shmem_align(3), shmem_realloc(3), plus their little lowercase alter egos shmalloc(3), shfree(3), shmemalign(3), and shrealloc(3) — all of them doing symmetric heap memory management 💖

This is straight out of Open MPI, and ngl it's lowkey the most iconic little family of functions you'll ever meet 🫶

---

✨ 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

She's giving header file realness. Copy it exactly, no cap 💅

---

💖 DESCRIPTION 💖

so. the way that shmem_malloc works is it returns a pointer to a block of at least size bytes, and that block is suitably aligned for any use 🌈 and here's the tea: this space comes from the symmetric heap</>, which is not the same as malloc(3), who is out here allocating from the humble private heap</> 🙈 contrast, periodt.

The shmem_align function allocates a block in the symmetric heap that has a byte alignment specified by the alignment argument 🎀 so if you need it lined up a very specific way, she's your girl.

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 ⚠️ (yes, double-free is a crime in this house.)

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 — like, genuinely nobody knows what's in there, do not trust it 😭 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. And 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 😳

fr fr, keep your PEs in sync bestie, it's giving group project energy and everyone has to show up 💀

---

🌸 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 further 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) — so like, no solo missions, this is a main character ensemble cast situation 💅

---

🌈 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 — she simply does her job and leaves, queen behavior 👑

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(3) shmem_init(3)

---

🦋 COPYRIGHT 🦋

2003-2026, The Open MPI Community

---

okay that's the whole page bestie, you ate 💅✨ this was SHREALLOC(3)</> from Open MPI, dated Sep 10, 2026 — go forth and allocate symmetrically, ily 🫶🎀💖