SHMALLOC(3)

✨ NAME ✨

shmalloc(3), shfree(3), shmemalign(3), shrealloc(3) — bestie, these are the symmetric heap memory management functions, from the Open MPI manual. 🌸

---

🦋 SYNOPSIS 🦋

C or C++:

#include <mpp/shmem.h>

void *shmalloc(size_t size)

void shfree(void *ptr)

void *shrealloc(void *ptr, size_t size)

void *shmemalign(size_t alignment, size_t size)

extern long malloc_error

---

💅 DESCRIPTION 💅

okay so picture this. 👑 shmalloc hands you back a pointer to a block of at least size bytes, and it's suitably aligned for any use. the whole vibe here is that this space comes from the symmetric heap — which is not what malloc(3) does, because malloc(3) is out here allocating from the private heap. different heap, different energy, iykyk. ✨

shmemalign is the alignment girlie 💖 — it allocates a block in the symmetric heap that has a byte alignment specified by the alignment argument. chef's kiss.

shfree is the clean-up queen 🧹 — it causes the block that ptr points to, to be deallocated, aka made available for further allocation. but listen:

• if ptr is a null pointer, no action occurs, we move on, periodt.
• otherwise, if the argument does not match a pointer earlier returned by a symmetric heap function, or if the space has already been deallocated, then malloc_error is set to indicate the error, and shfree returns. 🫠

shrealloc is the glow-up function 🦋 — it changes the size of the block that ptr points to, to the size (in bytes) you specified. here's the tea:

• 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 — so like, don't count on it, bestie. 🙈
• 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.
• if the space cannot be allocated, the block that ptr points to is unchanged. 💜

---

okay and now the why of it all. the shmalloc, shfree, and shrealloc functions are provided so that multiple PEs in an application can allocate symmetric, remotely accessible memory blocks. 🔥 those memory blocks can then be used with (shmem) communication routines. so real.

each of these functions calls 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. main character synchronization energy. ⭐

⚠️ and this part is your job, not the library's: 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. no cap. 💀

---

🎀 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 — see the intro_shmem(3) man page for further details. 🌸

also, the shmalloc, shfree, and shrealloc 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). yes, everybody. it's giving group project but make it functional. 🫶

---

🌟 RETURN VALUES 🌟

• shmalloc returns a pointer to the allocated space — which should be identical on all PEs — otherwise, it returns a null pointer (with malloc_error set). ✨
• shfree returns no value. that's it, that's the whole return. 💅
• shrealloc 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)
• my_pe(3)
• start_pes(3)

---

💖 COPYRIGHT 💖

2003-2026, The Open MPI Community

---

and that's the whole page, bestie!! 💜 this was the SHMALLOC(3) page from Open MPI, dated Sep 10, 2026 — go forth and allocate symmetrically, you absolute icon. 💅✨🎀