SHMEMALIGN(3)

💖 SHMEMALIGN — bestie, it's giving symmetric heap realness 💖

okay so. welcome to Open MPI's section 3 page for the whole symmetric-heap memory-management squad. we got four icon functions in the group chat: shmem_malloc(3), shmem_free(3), shmem_align(3), and shmem_realloc(3) — plus their lowercase aliases shmalloc(3), shfree(3), shmemalign(3), shrealloc(3). they're all about managing the symmetric heap. no cap. 🎀

---

✨ 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

like. look at that. so clean. 🫶

---

🌸 DESCRIPTION 🌸

so shmem_malloc hands you back a pointer to a block of at least size bytes, aligned all nicely so it works for literally any use. and the tea? this space comes out of the symmetric heap — which is the whole plot twist, because plain old malloc(3) takes from the private heap instead. different heaps, different vibes, okay? 💅

then shmem_align is the glow-up version: it allocates a block in the symmetric heap with a byte alignment you specify yourself with the alignment argument. you want it aligned? bestie you get to choose the alignment. iconic.

shmem_free does what it says on the tin — it deallocates the block that ptr points at, meaning that memory becomes available again for further allocation. now listen carefully because this part matters:

• if ptr is a null pointer, 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 was already deallocated — malloc_error gets set to indicate the error, and shfree returns. yikes. 🙈

shmem_realloc changes the size of the block that ptr points at, to the size in bytes specified by size. here's the fine print, don't skip it:

• 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 is indeterminate — like, whatever's in there, nobody knows, do not trust it. 💀
• if ptr is a null pointer, shrealloc behaves like shmalloc for that specified size.
• if size is 0 and ptr is not a null pointer, the block it points to gets freed.
• otherwise, if ptr doesn't match a pointer earlier returned by a symmetric heap function, or 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 just cannot be allocated? the block that ptr points to is left unchanged. at least there's that. 🫠

now for the why — the reason these three exist in the first place. shmem_malloc, shmem_free, and shmem_realloc are provided so that multiple PEs in one application can allocate symmetric, remotely accessible memory blocks. those blocks can then be used with (shmem) communication routines. main character energy fr fr. 👑

and here's the part that surprises people: each of these functions calls the shmem_barrier_all(3) function before returning. that barrier is doing the work — it makes sure all PEs participate in the memory allocation, and that the memory on other PEs can be used the second the local PE returns. ✨

⚠️ 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. so. don't do that. okayyyy? 💖

---

🦋 NOTES 🦋

the total size of the symmetric heap is determined at job startup. (not by you, not later, at startup. periodt.) if you wanna adjust the size of the heap, use the SHMEM_SYMMETRIC_HEAP_SIZE environment variable 🌈 — and for further details, go read the intro_shmem(3) man page.

also, the big difference between these and the private heap allocation functions: shmem_malloc, shmem_free, and shmem_realloc require all PEs in an application to call them (a barrier is used to ensure this). so it's a group activity. no solo missions. 🧚

---

⭐ 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's a void girlie, she gives nothing back. 💅
• shmem_realloc returns a pointer to the allocated space, which may have moved (important!! it can move!!) — 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, you ate it up fr 🍓✨ this drop is dated Sep 10, 2026, and the source is the Open MPI project — go forth and allocate symmetrically, you got this 💜🎀