The shmem_malloc_with_hints routine, like shmem_malloc, returns a pointer to
a block of at least size bytes, which shall be suitably aligned so that it
may be assigned to a pointer to any type of object. This space is allocated
from the symmetric heap (similar to shmem_malloc). When the size is zero,
the shmem_malloc_with_hints routine performs no action and returns a null
pointer.
In addition to the size argument, the hints argument is provided by the user.
The hints describes the expected manner in which the OpenSHMEM program may
use the allocated memory. The valid usage hints are described in Table 1.
Multiple hints may be requested by combining them with a bitwise OR operation.
A zero option can be given if no options are requested.
The information provided by the hints is used to optimize for performance by
the implementation. If the implementation cannot optimize, the behavior is
same as shmem_malloc. If more than one hint is provided, the implementation
will make the best effort to use one or more hints to optimize performance.
The shmem_malloc_with_hints routine is provided so that multiple PEs in a
program can allocate symmetric, remotely accessible memory blocks. When no
action is performed, these routines return without performing a barrier.
Otherwise, the routine will call a procedure that is semantically equivalent
to shmem_barrier_all on exit. 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. The implicit barrier performed by this routine will
quiet the default context. It is the user’s responsibility to ensure that no
communication operations involving the given memory block are pending on
other contexts prior to calling the shmem_free and shmem_realloc routines.
The user is also responsible for calling these routines with identical
argument(s) on all PEs; if differing size, or hints arguments are used, the
behavior of the call and any subsequent OpenSHMEM calls is undefined.