 |
Index for
Section 3 |
|
 |
Alphabetical
listing for N |
|
 |
Bottom of
page |
|
nmadvise(3)
NAME
nmadvise - 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 madvise(),
with the addition of the attr parameter:
addr
Points to the starting address of the range of pages to which the
advice refers.
len Starting at the address specified by the addr parameter, specifies the
length (in bytes) of the memory range.
behav
Specifies the expected behavior pattern for referencing pages in the
specified range. See DESCRIPTION for details.
attr
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 behavior to advise the
system about page placement without specifying any particular paging
behavior:
MADV_CURRENT
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.
MADV_WAIT
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.
MADV_INSIST
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.
NOTES
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.
RETURN VALUES
0 Success.
-1 Failure. In this case, errno is set to indicate the error.
ERRORS
If the nmadvise() function fails, it sets errno to one of the following
values for the reason specified:
[EBUSY]
MADV_DONTNEED was specified but pages could not be freed, most likely
because the specified memory range includes a wired page.
[EFAULT]
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.
[EINVAL]
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().
[ENOMEM]
The attr structure specifies a RAD that has no memory.
[ENOSPC]
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for N |
|
 |
Top of
page |
|