Provided by:
libnuma-dev_0.9-1_i386 
NAME
numa - NUMA policy library
SYNOPSIS
#include <numa.h>
cc ... -lnuma
int numa_available(void)
int numa_max_node(void)
int numa_preferred(void)
long numa_node_size(int node, long *freep)
long long numa_node_size64(int node, long long *freep)
nodemask_t numa_all_nodes
nodemask_t numa_no_nodes
int numa_node_to_cpus(int node, unsigned long *buffer, int bufferlen)
void numa_set_interleave_mask(nodemask_t *nodemask)
nodemask_t numa_get_interleave_mask(void)
void numa_bind(nodemask_t *nodemask)
void numa_set_preferred(int node)
void numa_set_localalloc(int flag)
void numa_set_membind(nodemask_t *nodemask)
nodemask_t numa_get_membind(void)
void *numa_alloc_interleaved_subset(size_t size, nodemask_t *nodemask)
void *numa_alloc_interleaved(size_t size)
void *numa_alloc_onnode(size_t size, int node)
void *numa_alloc_local(size_t size)
void *numa_alloc(size_t size)
void numa_free(void *start, size_t size)
int numa_run_on_node_mask(nodemask_t *nodemask)
int numa_run_on_node(int node)
int numa_get_run_node_mask(void)
void numa_interleave_memory(void *start, size_t size, nodemask_t
*nodemask)
void numa_tonode_memory(void *start, size_t size, int node)
void numa_tonodemask_memory(void *start, size_t size, nodemask_t
*nodemask)
void numa_setlocal_memory(void *start, size_t size)
void numa_police_memory(void *start, size_t size)
int numa_distance(int node1, int node2)
void numa_set_bind_policy(int strict)
void numa_set_strict(int strict)
void numa_error(char *where)
void numa_warn(int number, char *where, ...)
extern int numa_exit_on_error
DESCRIPTION
libnuma offers a simple programming interface to the NUMA policy
supported by the Linux kernel. On a NUMA (Non Uniform Memory Access)
architecture some memory areas have different latency or bandwidth than
others. Available policies are page interleaving, preferred node
allocation, local allocation, allocation only on specific nodes. It
also allows to bind threads to specific nodes. All policy exists per
thread, but is inherited to children. For setting global policy per
process it is easiest to run it using the numactl(8) utility. For more
finegrained policy inside an application this library can be used.
All numa memory allocation policy only takes effect when a page is
actually faulted into the address space of a process by accessing it.
The numa_alloc_* functions take care of this automatically.
A node is defined as an area where all memory has the same speed as
seen from a particular CPU. Caches are ignored for this definition.
The mapping of nodes to cpus depends on the architecture. On the AMD64
architecture each CPU is an own node. This library is only concerned
about nodes.
Before any other calls in this library can be used numa_available must
be called. When it returns an negative value all other functions in
this library are undefined.
numa_max_node returns the highest node number available on the current
system. When a node number or a node mask with a bit set above the
value returned by this function is passed to a libnuma the result is
undefined. The numa_node_size function returns the memory size of a
node. When the argument freep is not NULL the free memory of the node
is written to it. On error it returns -1. numa_node_size64 works the
same as numa_node_size except that it returns values as long long
instead of long. This is useful on 32bit architectures with large
nodes.
Some of these functions accept or return a nodemask. A nodemask has
type nodemask_t which is an abstract bitmap type containing a bit set
of nodes. The maximum node number depends on the architecture, but is
not bigger than NUMA_MAX_NODE. When happens in libnuma calls when bits
above numa_max_node are passed is undefined. An nodemask_t should be
only manipulated with the nodemask_zero, nodemask_clr, nodemask_isset,
nodemask_set functions. nodemask_zero clears an nodemask_t,
nodemask_isset returns true when node is set in the passed nodemask,
nodemask_clr clears node in nodemask, nodemask_set sets node in
nodemask. The predefined variable numa_all_nodes has all available
nodes set, numa_no_nodes is the empty set. nodeset_equal returns non
zero when the two nodesets are equal.
numa_preferred returns the preferd node of the current thread. It is
the node the kernel preferably allocates memory on, unless some other
policy overwrites this.
numa_set_interleave_mask Set an memory interleave mask for the current
thread to nodemask. All new memory allocations are page interleaved
over all nodes in the interleave mask. Interleaving can be turned off
again by passing a zero mask. The page interleaving only occurs on the
actual page fault that puts a new page into the current address space.
It is also only a hint, the kernel will fall back to other nodes if no
memory is available on the interleave target. This is a low level
function, it may be more convenient to use the higher level functions
like numa_alloc_interleaved or numa_alloc_interleaved_subset.
numa_get_interleave_mask returns the current interleave mask.
numa_bind binds the current thread and its children to the nodes
specified in nodemask. They will only run on the CPUs of the specified
nodes and only able to allocate memory from them. This function is
equivalent to calling numa_run_on_node_mask and numa_set_membind with
the same argument.
numa_set_preferred sets the preferred node for the current thread to
node. Preferred node is the node memory is preferably allocated from
before falling back to other nodes. The default is to use the current
node the process runs on (local policy). Passing an -1 argument is
equivalent to numa_set_localalloc.
numa_set_localalloc sets a local memory allocation policy for the
current thread. Memory is preferably allocated from the current node.
numa_set_membind sets the memory allocation mask. The thread will only
allocate memory from the nodes set in nodemask. Passing an argument of
numa_no_nodes or numa_all_nodes turns off memory binding to specific
nodes.
numa_get_membind returns the current node mask from which memory can be
allocated. numa_no_nodes or numa_all_nodes means all nodes are
available for memory allocation.
numa_alloc_interleaved allocates size bytes of memory page interleaved
on all nodes. This function is relatively slow and should only be used
for large areas consisting of multiple pages. The interleaving works on
page level and will only show an effect when the area is large. It must
be freed with numa_free. On errors NULL is returned.
numa_alloc_interleaved_subset is like numa_alloc_interleaved except
that it also accepts a mask of the nodes to interleave on. On errors
NULL is returned.
numa_alloc_onnode allocates memory on a specific node. This function is
relatively slow and allocations are rounded to pagesize. The memory
must be freed with numa_free On errors NULL is returned.
numa_alloc_local allocates size bytes of memory on the local node. This
function is relatively slow and allocations are rounded to pagesize.
The memory must be freed with numa_free. On errors NULL is returned.
numa_alloc allocates size bytes of memory with the current NUMA policy.
This function is relatively slow and allocations are rounded to
pagesize. The memory must be freed with numa_free. On errors NULL is
returned.
numa_free frees size bytes of memory starting at start, allocated by
the numa_alloc_* functions above.
numa_run_on_node runs the current thread and its children on a specific
node. They will not migrate to CPUs of other nodes until the node
affinity is reset with a new call to numa_run_on_node_mask. Passing -1
allows to schedule on all nodes again. Returns an negative value and
error in errno, or 0 on success.
numa_run_on_node_mask runs the current thread and its children only on
nodes specified in nodemask. They will not migrate to CPUs of other
nodes until the node affinity is reset with a new call to
numa_run_on_node_mask. Passing numa_all_nodes allows to schedule on
all nodes again. Returns an negative value and error in errno, or 0 on
success.
numa_get_run_node_mask returns the mask of nodes that the current
thread is allowed to run on.
numa_interleave_memory pages interleaves size bytes memory from start
on nodes nodemask. This is a lower level function to interleave not
yet faulted in but allocated memory. Not yet faulted in means the
memory is allocated using mmap(2) or shmat(2), but has not been
accessed by the current process yet. The memory is page interleaved to
all nodes specified in nodemask. Normally numa_alloc_interleaved
should be used for private memory instead, but this function is useful
to handle shared memory areas. To be useful the memory area should be
significantly larger than a page. When the numa_set_strict flag is
true then the operation will cause an numa_error if there were already
pages in the mapping that do not follow the policy.
numa_tonode_memory put memory on a specific node. The constraints
described for numa_interleave_memory apply here too.
numa_tonodemask_memory put memory on a specific set of nodes. The
constraints described for numa_interleave_memory apply here too.
numa_setlocal_memory locates memory on the current node. The
constraints described for numa_interleave_memory apply here too.
numa_police_memory locates memory with the current NUMA policy. The
constraints described for numa_interleave_memory apply here too.
numa_node_to_cpus converts a node number to a bitmask of cpus. The user
must pass a long enough buffer. When the buffer is not long enough
errno will be set to ERANGE and -1 returned. On success 0 is returned.
numa_set_bind_policy specifies whether calls that bind memory to a
specific node should use the preferred policy or a strict policy.
Preferred allows to allocate memory on other nodes when there isn’t
enough free on the target node. strict will fail the allocation in that
case. Setting the argument to specifies strict, 0 preferred. Note
that specifying more than one node non strict may only use the first
node in some kernel versions.
numa_set_strict sets a flag that says whether the functions allocating
on specific nodes should use use a strict policy. Strict means the
allocation will fail if the memory cannot be allocated on the target
node. Default operation is to fall back to other nodes. This doesn’t
apply to interleave and default.
numa_distance reports the distance in the machine topology between two
nodes. The factors are a multiple of 10. It returns 0 when the
distance cannot be determined. A node has distance 10 to itself.
Reporting the distance requires a Linux kernel version of 2.6.10 or
newer.
numa_error is an weak internal libnuma function that can be overwritten
by the user program. It allows to specify a different error handling
strategy when an NUMA system call fails. It does not affect
numa_available.
The default action is to print an error to stderr and exit the program
when numa_exit_on_error is set to a non zero value. Default is zero.
numa_warn is a weak internal libnuma function that can be also
overwritten by the user program. It is called when a non fatal error
occurs to warn the user. The default implementation prints a warning to
stdout.
The first argument is an unique number identifying each warning. After
that there is a printf(3) style format string and a variable number of
arguments.
THREAD SAFETY
numa_set_bind_policy and numa_exit_on_error are process global. The
other calls are thread safe. Memory policy for an specific memory when
changed affects the whole process and possible other processes mapping
the same memory.
COPYRIGHT
Copyright 2002,2004 Andi Kleen, SuSE Labs. libnuma is under the GNU
Lesser General Public License, v2.1.
SEE ALSO
getpagesize(2) mmap(2) shmat(2) numactl(8)