18.2.190. shmem_realloc

shmem_malloc(3), shmem_free(3), shmem_align(3), shmem_realloc(3) shmalloc(3), shfree(3), shmemalign(3), shrealloc(3) - 对称堆内存管理函数

18.2.190.1. 概述

C或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

18.2.190.2. 描述

shmem_malloc 函数返回一个指向至少 size 字节内存块的指针，该内存块经过适当对齐可用于任何用途。此空间从对称堆中分配（与从私有堆分配的 malloc(3) 形成对比）。

shmem_align 函数会在对称堆中分配一个内存块，该内存块的字节对齐方式由 alignment 参数指定。

shmem_free函数的作用是释放ptr指针所指向的内存块，使其可被重新分配。如果ptr为空指针，则不执行任何操作；否则，若参数与对称堆函数先前返回的指针不匹配，或该内存空间已被释放，则将设置malloc_error以指示错误，并返回shfree。

shmem_realloc 函数将指针 ptr 所指向的内存块大小更改为由 size 参数指定的字节数。

块的内容在不超过新旧尺寸较小值的情况下保持不变。如果新尺寸更大，则新分配部分的值是不确定的。如果ptr为空指针，shrealloc函数的行为类似于指定大小的shmalloc函数。如果size为0且ptr不是空指针，则释放其指向的块。否则，如果ptr与之前对称堆函数返回的指针不匹配，或者空间已被释放，则设置malloc_error变量以指示错误，并且shrealloc返回空指针。如果无法分配空间，则ptr指向的块保持不变。

提供shmem_malloc、shmem_free和shmem_realloc函数， 以便应用程序中的多个PE可以分配对称且可远程访问的内存块。这些内存块随后可用于 (shmem)通信例程。这些函数在返回前都会调用 shmem_barrier_all(3)函数；这确保了 所有PE都参与内存分配，并且其他PE上的内存 在本地PE返回后即可使用。

用户有责任在所有PE上使用相同的参数调用这些函数；如果使用了不同大小的参数，后续调用可能无法在所有PE上返回相同的对称堆地址。

18.2.190.3. 注意事项

对称堆的总大小在作业启动时确定。用户可以通过SHMEM_SYMMETRIC_HEAP_SIZE环境变量调整堆的大小。更多详情请参阅intro_shmem(3)手册页。shmem_malloc、shmem_free和shmem_realloc函数与私有堆分配函数的不同之处在于，应用程序中的所有PE都必须调用它们（使用屏障来确保这一点）。

18.2.190.4. 返回值

shmem_malloc函数返回指向已分配空间的指针（在所有PE上应相同）；否则返回空指针（并设置malloc_error）。shmem_free函数不返回值。shmem_realloc函数返回指向重新分配空间的指针（地址可能发生变化）；否则返回空指针（并设置malloc_error）。

另请参阅

intro_shmem(3) shmem_my_pe(3) shmem_init(3)