nmadvise(3)nmadvise(3)NAMEnmadvise - Advise the system of the expected paging behavior of a
process (libnuma)
SYNOPSIS
#include <numa.h> #include <sys/nman.h>
int nmadvise(
void *addr,
long len,
int behav,
memalloc_attr_t *attr );
PARAMETERS
The parameters to the nmadvise() function are the same as for mad‐
vise(), with the addition of the attr parameter: Points to the starting
address of the range of pages to which the advice refers. Starting at
the address specified by the addr parameter, specifies the length (in
bytes) of the memory range. Specifies the expected behavior pattern
for referencing pages in the specified range. See DESCRIPTION for
details. Points to a structure containing the memory allocation policy
and attributes that will be assigned to the specified range. See the
entry for memalloc_attr_t in numa_types(4) for a description of this
structure.
DESCRIPTION
The nmadvise() function permits a process to advise the system about
its expected behavior in referencing a particular range of pages in the
process address space. This advice includes reference patterns that the
system can use to optimize page fault behavior (as also supported by
madvise()), plus NUMA locality information that the system can use to
optimize the placement of the pages that are allocated in response to
page faults.
The nmadvise() function supports the following flags to be ORed with
one of the behav values documented in madvise(2). The normal practice
is to OR one or more of the following flags with the MADV_NORMAL behav‐
ior to advise the system about page placement without specifying any
particular paging behavior: Prepare the specified range or object for
migration to the memory region specified by the memory allocation pol‐
icy and associated attributes. Migration means that pages already allo‐
cated in the specified range will be copied to new pages that are allo‐
cated according to the NUMA policy and attributes as specified by the
attr parameter. Without this flag, only new allocations in the speci‐
fied range will be allocated according to the specified policy and
attributes.
See the discussion following this list for information about the
effect of ORing this flag with the MADV_DONTNEED behavior value.
This flag may be logically ORed with another behav flag to indi‐
cate that the requested operation be performed before returning
from the function call.
Without this flag, the nmadvise() function will return as soon
as the new memory allocation policy and attributes are in place
and, if MADV_DONTNEED is also specified, the currently allocated
pages are discarded. In this case, migration of page contents
(if MADV_CURRENT is specified and MADV_DONTNEED is not speci‐
fied) or new allocations of zeroed pages in accordance with the
specified policy and attributes does not occur until the program
touches a page in the specified range. This flag may be logi‐
cally ORed with another behavflag to request that the program be
notified if the specified operation cannot be performed. This
flag is currently ignored.
Except for MADV_DONTNEED, the behav flags supported by both madvise()
and nmadvise() are equivalent. In other words, the behav information is
orthogonal to the additional NUMA information (the memory allocation
policy and associated attributes) that the nmadvise() function pro‐
vides. However, MADV_DONTNEED has special significance in the context
of memory location changes within the NUMA topology. The nmadvise()
call uses behav flags as follows to specify how currently allocated
pages are to be handled when the requested NUMA allocation policy and
attributes are applied: MADV_DONTNEED tells the system to discard the
contents of any pages currently allocated for the process or thread and
then perform future allocations according to the specified NUMA policy
and attributes. MADV_CURRENT (without MADV_DONTNEED) requests that, if
the NUMA policy and attributes indicate that page allocations should
start in a location different from the location of pages already allo‐
cated, the contents of the already allocated pages should be migrated
to the new location.
The MADV_CURRENT is ignored when ORed with MADV_DONTNEED because
the specified behavior is to discard currently allocated pages.
Omitting both MADV_CURRENT and MADV_DONTNEED preserves the con‐
tents of already allocated pages at their current location and
allows only future page allocations to be made according to the
specified NUMA policy and attributes.
Future page allocations that are performed according to the specified
NUMA policy and attributes will be initialized to zero unless the mem‐
ory allocation is performed to map a file from disk, in which case the
memory pages are inititalized from disk.
If, in the structure pointed to by attr, the mattr_policy member is
MPOL_DIRECTED, then the mattr_radset member specifies the Resource
Affinity Domain (RAD) from which pages will be allocated for virtual
addresses in the specified range (addr to addr+len). If the mattr_pol‐
icy member is MPOL_THREAD, then pages for the virtual addresses in the
specified thread will be allocated from the faulting thread's home RAD.
If the mattr_policy member is MPOL_DIRECTED or MPOL_THREAD, then the
mattr_radset member specifies the overflow behavior when there is no
free memory on the preferred RAD. If mattr_radset is NULL (in other
words, no RAD set), then the overflow set is taken to be the set of all
RADs in the caller's partition. If mattr_radset specifies an empty RAD
set, no overflow RAD set is requested and the process or thread will
wait for memory to become available on the preferred RAD.
If the attr parameter is a NULL pointer, any behav flags specific to
nmadvise()are ignored, and the function is equivalent to madvise(). In
this case, any behav flags specific to nmadvise() (in other words, not
supported by the madvise() function) are treated as invalid.
NOTES
As with madvise(), the behaviors specified with nmadvise() are consid‐
ered by the system to be hints, and may in fact, be unimplemented.
Unimplemented behaviors will always return success.
Furthermore, the operating system always attempts to replicate program
text and shared library text on all RADs, so any request to change the
memory allocation policy for these parts of the application's address
space is always silently ignored.
RETURN VALUES
Success. Failure. In this case, errno is set to indicate the error.
ERRORS
If the nmadvise() function fails, it sets errno to one of the follow‐
ing values for the reason specified: MADV_DONTNEED was specified but
pages could not be freed, most likely because the specified memory
range includes a wired page. A non-NULL attr argument points to an
invalid address, or the range of pages (addr, len) includes a wired
page or “hole” in the virtual address space. One of the following con‐
ditions is true: The value of the behav parameter or a member of the
attr structure (the specified RAD, RAD set, or memory allocation pol‐
icy) is invalid. The attr parameter is a NULL pointer (which makes the
nmadvise() call equivalent to an madvise() call) and the logical OR
operation on behav values includes one or more flags supported only by
nmadvise(). The attr structure specifies a RAD that has no memory.
The behav parameter specifies MADV_SPACEAVAIL, and resources cannot be
reserved.
SEE ALSO
Functions: madvise(2), nshmget(3), nmmap(3), numa_intro(3)
Files: numa_types(4)nmadvise(3)