nmadvise - Advise the system of the expected paging behavior
of a process (libnuma)
#include <numa.h> #include <sys/nman.h>
int nmadvise(
void *addr,
long len,
int behav,
memalloc_attr_t *attr );
The parameters to the nmadvise() function are the same as
for madvise(), 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.
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 behavior 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 policy and associated attributes. Migration
means that pages already allocated in the specified
range will be copied to new pages that are allocated
according to the NUMA policy and attributes as specified
by the attr parameter. Without this flag, only new allocations
in the specified 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 indicate
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 specified) 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
logically 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 provides.
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
allocated, 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 contents
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 memory 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_policy 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.
As with madvise(), the behaviors specified with nmadvise()
are considered 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.
Success. Failure. In this case, errno is set to indicate
the error.
If the nmadvise() function fails, it sets errno to one of
the following 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 conditions is true: The value of the behav
parameter or a member of the attr structure (the specified
RAD, RAD set, or memory allocation policy) 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.
Functions: madvise(2), nshmget(3), nmmap(3), numa_intro(3)
Files: numa_types(4)
nmadvise(3)
[ Back ] |
