SHFREE(3)

✨ NAME ✨

okay so bestie, welcome to the Open MPI manual page for shfree(3) — and it's not just one function, it's a whole squad 🫶

• shmem_malloc(3), shmem_free(3), shmem_align(3), shmem_realloc(3)
• shmalloc(3), shfree(3), shmemalign(3), shrealloc(3)

...they're the symmetric heap memory management functions. that's the vibe. that's the whole job. ✨

---

🌸 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 the shmem_malloc function hands you back a pointer to a block of at least size bytes, suitably aligned for literally any use. and here's the tea ☕: this space comes out of the symmetric heap — not the private heap like plain old malloc(3) does. different heap, different girl. 💁

the shmem_align function allocates a block in the symmetric heap that has a byte alignment specified by the alignment argument. you want it aligned? bestie, it's aligned. ✨

the shmem_free function makes the block that ptr points to get deallocated — like, made available for further allocation, it's freed, it's gone, we release it back to the universe 🦋

but watch out: if ptr is a null pointer, nothing happens, no action occurs. BUT otherwise — if the argument doesn't match a pointer that a symmetric heap function handed out earlier, or if that space has already been deallocated — then malloc_error gets set to indicate the error, and shfree returns. that's double-free energy and we do not stan. 😭

the shmem_realloc function changes the size of the block to which ptr points, to the size (in bytes) specified by size. glow up?? maybe. 💖

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 — so don't come for it, we simply don't know her yet. 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 gets 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 just cannot be allocated, the block to which ptr points stays unchanged. no harm, no foul, no relocation. 🧚

the shmem_malloc, shmem_free, and shmem_realloc functions 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. iconic behavior, truly. 👑

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. group project that actually works?? a miracle. 🙈

⚠️ the user is responsible for calling these functions with identical argument(s) on all PEs. if differing size arguments get used, subsequent calls may not return the same symmetric heap address on all PEs. so like... coordinate, bestie. communication is key. 😭

---

🎀 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, iykyk. 📖

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 yeah, it's giving main character energy but make it a collective — everyone's in the scene or nobody is. 💫

---

⭐ 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. nothing. void. silence. 💀
• 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

---

and that's the whole page, bestie!! 💖 this was brought to you by Open MPI, dated Sep 10, 2026 — go forth, allocate symmetrically, and free responsibly. slay. 💅✨