numa_types(4)numa_types(4)NAMEnuma_types - Data types used by NUMA application interfaces
SYNOPSIS
#include <sys/numa_types.h>
DESCRIPTION
This reference page lists and describes the data types, flags, struc‐
tures, and unions that are defined in the <numa_types.h> header file to
support the HP Tru64 UNIX NUMA APIs.
The program must call radsetcreate() or cpusetcreate() to allocate the
RAD set or CPU set associated with any fields defined as type radset_t
or cpuset_t, respectively.
Note that numa_types.h is indirectly included by the <numa.h> header
file, which is the header file more frequently specified in the SYNOP‐
SIS sections of reference pages for NUMA-related functions.
Definitions
The <numa_types> header defines the following data types, flags, struc‐
tures, and unions, and associated symbolic values: Reserved for future
use. A structure type that defines the policy and associated parame‐
ters for memory allocation. The memalloc_attr structures are associ‐
ated with memory objects and with processes and threads. This structure
contains the following members: Specifies the memory allocation policy
(as described in the entry for memalloc_policy_t). Remaining members of
the structure contain parameters used to implement this policy. Speci‐
fies the primary or preferred RAD (region) from which to allocate mem‐
ory for the MPOL_DIRECTED memory allocation policy. Specifies the dis‐
tance to overflow. This value is not currently used for any memory
allocation policy. Specifies the stride (in pages) for the
MPOL_STRIPED memory allocation policy. Specifies the page size in
bytes. This value is not currently used for any memory allocation pol‐
icy. If mattr_policy is MPOL_DIRECTED or MPOL_THREAD, specifies the
overflow RAD set.
If mattr_policy is MPOL_STRIPED, specifies the RAD set across
which memory is striped. An enumeration type that determines,
along with associated parameter attributes, how memory will be
allocated for a memory object or a kernel memory allocation
request. Valid policy values are: Allocate pages from a speci‐
fied (meaning preferred) RAD with overflow into a specified,
possibly NULL, overflow RAD set. Equivalent to MPOL_DIRECTED
but having the thread context determine the preferred RAD from
which pages are allocated. (In this case, the mattr_rad value is
ignored.) Allocate pages so that they are striped across a
specified RAD set by using a specified (page multiple) stripe as
specified by the mattr_stride member of the memalloc_attr_t
structure. Starting with a specified RAD, pages will be allo‐
cated from RADs in the RAD set in order of increasing RAD num‐
ber. An mattr_stride number of pages will be allocated from each
RAD before pages are allocated from the next RAD. After pages
are allocated from the highest numbered RAD in the set, alloca‐
tion will wrap, which means that pages are next allocated from
the lowest numbered RAD in the set. Replicate pages on the home
RAD of the thread that caused the pages to be allocated.
Note
MPOL_REPLICATED is the default and only memory allocation policy
supported for shared library text pages and program text pages.
Furthermore, the operating system ignores MPOL_REPLICATED when
it is specified for other types of memory (stack, heap, and
shared data pages). Therefore, specifying MPOL_REPLICATED has
no effect in the current implementation.
The following modifier may be combined (by using a logical OR
operation) with the preceding policies: Disable automatic migra‐
tion of pages by the system.
The following table indicates how different memory policies are
supported for the different types of memory in the program
address space:
SHPT = shared program text
SHLT = shared library text
SVSHM = System V shared memory
STACK = program or thread stack
DATA = initialized program data
BSS = uninitialized program data and heap
MPRIV = [n]mmap(MAP_PRIVATE)
MSHAR = [n]mmap(MAP_SHARED)
MANON = [n]mmap(MAP_ANONYMOUS)
──────────────────────────────────────────────────────────────────────────
MPOL_DIRECTED MPOL_THREAD MPOL_STRIPED MPOL_REPLI‐
CATED
──────────────────────────────────────────────────────────────────────────
SHPT Ignored * Ignored * Ignored * Default
SHLT Ignored * Ignored * Ignored * Default
SVSHM As specified. As specified Default *** =MPOL_DIRECTED
but no migra‐
tion. **
STACK As specified. Default As specified. =MPOL_DIRECTED
DATA As specified. Default As specified =MPOL_DIRECTED
BSS As specified. Default As specified. =MPOL_DIRECTED
MPRIV As specified. Default As specified. =MPOL_DIRECTED
MSHAR As specified. Default As specified. =MPOL_DIRECTED
MANON As specified. Default As specified. =MPOL_DIRECTED
──────────────────────────────────────────────────────────────────────────
“Ignored” means only that the MPOL_* flag is ignored; the nmad‐
vise() call is still checked for errors and any applicable
behaviors are performed. When thread-local memory allocation is
specified for System V shared memory segments, the policy is
used only for pages that have not yet been allocated, have been
paged out, or have been discarded (by means of the MADV_DONTNEED
flag on an nmadvise() call). Existing pages are not migrated
according to the new memory allocation policy in order to avoid
thrashing; in other words, the MADV_CURRENT flag on a nmadvise()
call is treated as MADV_DONTNEED with respect to System V shared
memory segments. The default memory allocation policy for Sys‐
tem V shared memory segments is configurable. If the shm_allo‐
cate_striped attribute of the IPC kernel subsystem is set to 1
(the default), SVSHM segments are striped. If this attribute is
set to 0, SVSHM segments are allocated by using the thread local
policy (MPOL_THREAD). Structures of this type are supported for
internal use only. Identifier for a NUMA Scheduling Group
(NSG). A structure that describes the NUMA topology attributes.
This structure is used with the nloc() function to query the
NUMA system topology or with the nfork() function to specify the
set of RADs from which a RAD will be selected for a new process.
This structure contains the following members: The type of
resource (as described in the entry for type rsrctype_t). The
resource descriptor, which identifies the instance of the
resource specified by the nattr_type value. Specify this field
as a union with the appropriate resource handle as described in
the entry for rsrcdescr_t. For example, a resource descriptor
for a RAD set might be specified as:
nat.nattr_descr.rd_radset
For this descriptor, nat is a structure of type numa_attr_t,
rd_radset is the resource handle, and nat.nattr_type has been
set to R_RAD. The distance to the requested resource. The
nloc() function returns a set of RADs that are less than or
equal this distance from the specified resource. Symbolic val‐
ues used by certain functions. The nloc(3) and nfork(3) refer‐
ence pages list and describe these values. Identifier for a
Resource Affinity Domain (RAD), which is a grouping of basic
system resources that form a NUMA building block. NUMA platforms
contain multiple RADs, and each RAD can contain zero or more
CPUs, memory arrays, and I/O busses. Single-processor and multi‐
processor platforms that do not use NUMA architecture are
treated by the operating system as single-RAD systems.
The radid_t data type is a generic, integral type, for which
there is the following symbolic value: No valid RAD ID. Func‐
tions return RAD_NONE when no RAD matches the specified crite‐
ria, there are no more RADs in a RAD set, and so forth. A set
of RADs. This type is used to specify a set of radid_t values to
the NUMA APIs. A subset of these APIs perform operations on a
set of RADs and manage radset_t as an opaque type. A opaque
type used in an enumeration or an iteration operation on a RAD
set. This type stores the current cursor position during a scan
of the members in a RAD set. See rad_foreach(3) for more infor‐
mation. A structure returned by the rad_get_info() function to
describe the state and resources associated with a RAD. This
structure contains the following members: The RAD revision num‐
ber. The RAD identifier. The RAD state, whose values are
listed in the description of the rad_state_t type. The amount
of physical memory present in the RAD. The current amount of
free memory available in the RAD. The set of CPUs associated
with the RAD.
See rad_get_info(3) for more information about querying RAD
information. A RAD's software state. The defined states are:
The specified RAD exists and is on line. Processes and threads
may be assigned to and memory allocated to the RAD. The speci‐
fied RAD exists but is not currently on line. No processes or
threads may be assigned to, nor memory allocated to, this RAD;
however, its resource complement may be queried.
Note
RAD_ONLINE is the only state currently supported. An enumera‐
tion type that specifies the kind of resource with which affin‐
ity is desired. Functions that perform NUMA topology queries and
resource binding pass rsrctype_t arguments along with rsrcde‐
scr_t descriptors to identify resources. The following symbolic
values identify the type of resource being specified by a par‐
ticular descriptor: A RAD set. A file or device referenced by
an open file descriptor. A file or device specified by a path‐
name. A System V shared memory segment that is referenced by a
shared memory ID. A process that is referenced by a pid_t iden‐
tifier. A physical memory mapped region that is referenced by a
process virtual address. This resource type is used to find RADs
that are equal to or less than a specified distance from a par‐
ticular memory location. See nloc(3). A NUMA Scheduling Group
that is referenced by an nsgid_t identifier. A union of the
various resource handles, or descriptors, that are specified by
different resource type (rsrctype_t) values. Along with an rsrc‐
type_t argument, an rsrcdescr_t handle is included on the
nattr_descr argument to the NUMA APIs that perform NUMA topology
queries and resource binding. The resource handles for different
resource types are as follows: If the rsrctype_t value is R_RAD,
a RAD set is the resource, for which rd_radset is the handle.
If the rsrctype_t value is R_FILDES, an open file or device
(referenced by descriptor) is the resource, for which rd_fd is
the handle. If the rsrctype_t value is R_PATH, a file or device
(referenced by pathname) is the resource, for which rd_pathname
is the handle. If the rsrctype_t value is R_SHM, a System V
shared memory segment is the resource, for which rd_shmid is the
handle. If the rsrctype_t value is R_PID, a process is the
resource, for which rd_pid is the handle. If the rsrctype_t
value is R_MEM, a mapped region of virtual memory is the
resource, for which rd_addr is the handle. If the rsrctype_t
value is R_NSG, a NUMA Scheduling Group is the resource, for
which rd_nsg is the handle.
See nloc(3) and nfork(3) for information about using rsrcdescr_t
handles to query and bind resources in the context of NUMA sys‐
tem topology. A structure that specifies the access permissions
and associated parameters and statistics for a NUMA Scheduling
Group (NSG). This structure contains the following members: A
subordinate structure that contains the NSG access permissions.
The number of processes attached to the NSG. A structure that
specifies a thread (process ID and thread ID) attached to an
NSG. This structure contains the following members: The process
ID of a thread that is attached to an NSG. The thread ID
(index) of a thread that is attached to an NSG.
SEE ALSO
Functions: nfork(3), nloc(3), numa_intro(3), rad_foreach(3),
rad_get_info(3)numa_types(4)