SHMEM_ALIGN(3)

📦
version 5.0.10 · 4 versions
, in ubuntu stonking

🎀 NAME 🎀

okay so hi bestie, welcome to SHMEM_ALIGN(3), a very Open MPI manual page 💖 it's the whole symmetric heap memory management squad, and it covers all of these divas:

— Symmetric heap memory management functions. periodt. 💅

✨ SYNOPSIS ✨

C or C++ (yes both, we don't discriminate 🫶):

#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 💫

The shmem_malloc function hands you back a pointer to a block of at least size bytes, suitably aligned for any use. and like… where does it come from? the symmetric heap, bestie. not the private heap. that's the whole plot twist, because malloc(3) allocates from the private heap. different vibes entirely 💀

The shmem_align function allocates a block in the symmetric heap that has a byte alignment specified by the alignment argument. so if you're picky about alignment (and you should be, queen), this is your girl ✨

The shmem_free function causes the block to which ptr points to, to be deallocated, that is, made available for further allocation. now listen:

  • If ptr is a null pointer, no action occurs. nothing. silence. iconic. 🙈
  • 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.

so like, double-freeing or passing a random pointer? it WILL clock you and set that error flag, no cap.

The shmem_realloc function changes the size of the block to which ptr points to, to the size (in bytes) specified by size.

and here's the fine print, bestie, read it carefully:

  • 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 don't trust it, don't read it, don't look at it).
  • 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 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 to which 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 call 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. it's giving synchronized group chat energy 👑

⚠️ 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 with your friends. please. 🙏

📝 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 further details.

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). no solo missions allowed, it's a group activity 💞

🫶 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. that's it. that's the whole return. bye 💅
  • 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).
lowkey important: realloc'd memory can move. re-check your pointer, bestie, don't hold onto the old one 🔥

🌈 SEE ALSO 🌈

2003-2026, The Open MPI Community

okay that's the whole page, you ate it, go forth and allocate symmetrically 🦋✨ this was SHMEM_ALIGN(3) from the Open MPI crew, dated Sep 10, 2026 — mwah, love u, bye 💖🎀🌸

📦 where this page comes from