SHMALLOC(3)

💖 SHMALLOC(3) 💖

okay so bestie, this is the Open MPI manual page for SHMALLOC(3) — symmetric heap memory management, but make it group-chat. It's giving "all your PEs have to agree on the allocation vibe," and honestly? main character energy.

---

✨ NAME ✨

• shmem_malloc(3), shmem_free(3), shmem_align(3), shmem_realloc(3), shmalloc(3), shfree(3), shmemalign(3), shrealloc(3) — symmetric heap memory management functions. That's the whole squad, 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;

---

💅 DESCRIPTION 💅

okay so here's the tea, function by function:

• shmem_malloc returns a pointer to a block of at least size bytes, suitably aligned for any use. This space is allocated from the symmetric heap — not the private heap like malloc(3C) does. periodt.
• shmem_align allocates a block in the symmetric heap that has a byte alignment specified by the alignment argument. slay.
• shmem_free causes the block that ptr points to to be deallocated, aka 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 bestie, the original specifically says shfree there 🫶
• shmem_realloc changes the size of the block that 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. that means don't trust it, bestie 😭
  • 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 that 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.

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 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. barrier girlies rise 🌈

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. that's the warning, don't ignore it 💀

---

🫶 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 futher details. (the page literally says "futher" — typo preserved, bestie 😭)
• 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). important!! 🚨

---

🎀 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.
• shmem_realloc returns a pointer to the allocated space (which may have moved); otherwise, it returns a null pointer (with malloc_error set).

that's the whole return tea on this page, no extra lore ✨

---

🦋 SEE ALSO 🦋

• intro_shmem(3)
• shmem_my_pe(3I)
• shmem_init(3)

---

okay that's the whole page! the footer stamp is gitclone / Unreleased developer copy / SHMALLOC(3), with no date shown — dev-copy vibes only. go forth and allocate symmetrically, bestie 💖✨