SHMEM_FREE(3)

🌸 SHMEM_FREE(3) — bestie, it's giving symmetric heap 💅

okay so this one's from Open MPI, and it's a whole family situation. We're talking 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). What are they? Symmetric heap memory management functions. That's it, that's the pitch. 🎀

---

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

So 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? That space comes out of the symmetric heap — not the private heap like malloc(3) does. Different heap, different vibe, iykyk. ✨

Then shmem_align allocates you a block in the symmetric heap too, but with a byte alignment specified by the alignment argument. Fancy. 💅

shmem_free deallocates the block that ptr points to — like, makes it available for further allocation again. If ptr is a null pointer, nothing happens, no action, we move on. Otherwise, though? If that argument doesn't match a pointer that a symmetric heap function returned earlier, OR if the space has already been deallocated, then malloc_error gets set to indicate the error, and shfree just returns. Not me getting caught slipping with a stale pointer 😭.

shmem_realloc changes the size of the block that ptr points to, to the size (in bytes) specified by size. Glow up, but for memory.

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 that newly allocated portion of the block is indeterminate — like, nobody knows, it's a mystery, don't trust it bestie. If ptr is a null pointer, then 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 doesn't 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 stays unchanged. 🫶

Now here's the group-project lore: shmem_malloc, shmem_free, and shmem_realloc exist so that multiple PEs in an application can allocate symmetric, remotely accessible memory blocks. Those blocks then get used with (shmem) communication routines. And every single one of these functions calls the shmem_barrier_all(3) function before returning — which is what makes sure all the PEs participate in the memory allocation, and that the memory on other PEs can be used as soon as the local PE returns. Everyone shows up to the function, no ghosting. 👑

⚠️ 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. So like. Coordinate. Please. fr fr. 💀

---

🎀 NOTES 🎀

The total size of the symmetric heap is determined at job startup. 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, bestie. 👀

And the way that shmem_malloc, shmem_free, and shmem_realloc differ from the private heap allocation functions is that all PEs in an application must call them — a barrier is used to ensure this. No solo missions allowed. 🚫

---

⭐ RETURN VALUES ⭐

• shmem_malloc 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 returns no value. Nothing. Zero. Nada. It just did the thing.
• shmem_realloc returns a pointer to the allocated space (which may have moved — lowkey iconic of it); otherwise, it returns a null pointer (with malloc_error set).

🌈 See also

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

---

💖 Copyright 💖

And that's the whole page, bestie, you ate that. 🍓 Before you go: this lil masterpiece is 2003-2026, The Open MPI Community, and it was last touched on Sep 10, 2026 — which is also the source/version and date stamped on SHMEM_FREE(3) down at the bottom. periodt. 🧚💜