 |
Index for
Section 4 |
|
 |
Alphabetical
listing for N |
|
 |
Bottom of
page |
|
numa_types(4)
NAME
numa_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, structures,
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 SYNOPSIS sections
of reference pages for NUMA-related functions.
Definitions
The <numa_types> header defines the following data types, flags,
structures, and unions, and associated symbolic values:
iopath_t
Reserved for future use.
memalloc_attr_t
A structure type that defines the policy and associated parameters for
memory allocation. The memalloc_attr structures are associated with
memory objects and with processes and threads. This structure contains
the following members:
memalloc_policy_t mattr_policy
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.
radid_t mattr_rad
Specifies the primary or preferred RAD (region) from which to
allocate memory for the MPOL_DIRECTED memory allocation policy.
int mattr_distance
Specifies the distance to overflow. This value is not currently
used for any memory allocation policy.
int mattr_stride
Specifies the stride (in pages) for the MPOL_STRIPED memory
allocation policy.
int mattr_pagesz
Specifies the page size in bytes. This value is not currently used
for any memory allocation policy.
radset_t mattr_radset
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.
memalloc_policy_t
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:
MPOL_DIRECTED
Allocate pages from a specified (meaning preferred) RAD with
overflow into a specified, possibly NULL, overflow RAD set.
MPOL_THREAD
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.)
MPOL_STRIPED
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 allocated from
RADs in the RAD set in order of increasing RAD number. 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, allocation
will wrap, which means that pages are next allocated from the
lowest numbered RAD in the set.
MPOL_REPLICATED
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:
MPOL_NO_MIGRATE
Disable automatic migration 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_REPLICATED
__________________________________________________________________________
Ignored * Ignored * Default
SHPT
Ignored *
Ignored * Ignored * Default
SHLT
Ignored *
As specified. Default ***
SVSHM
As specified
but no
migration. **
=MPOL_DIRECTED
As specified. As specified.
STACK
Default
=MPOL_DIRECTED
As specified. As specified
DATA
Default
=MPOL_DIRECTED
As specified. As specified.
BSS
Default
=MPOL_DIRECTED
As specified. As specified.
MPRIV
Default
=MPOL_DIRECTED
As specified. As specified.
MSHAR
Default
=MPOL_DIRECTED
As specified. As specified.
MANON
Default
=MPOL_DIRECTED
__________________________________________________________________________
* "Ignored" means only that the MPOL_* flag is ignored; the
nmadvise() 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 System V shared memory
segments is configurable. If the shm_allocate_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).
nmemalloc_range_t
Structures of this type are supported for internal use only.
nsgid_t
Identifier for a NUMA Scheduling Group (NSG).
numa_attr_t
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:
rsrctype_t nattr_type
The type of resource (as described in the entry for type
rsrctype_t).
rsrcdescr_t nattr_descr
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.
ulong nattr_distance
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.
ulong nattr_flags
Symbolic values used by certain functions. The nloc(3) and
nfork(3) reference pages list and describe these values.
radid_t
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 multiprocessor
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:
RAD_NONE
No valid RAD ID. Functions return RAD_NONE when no RAD matches the
specified criteria, there are no more RADs in a RAD set, and so
forth.
radset_t
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.
rad_cursor_t
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 information.
rad_info_t
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:
int rinfo_version
The RAD revision number.
radid_t rinfo_radid
The RAD identifier.
rad_state_t rinfo_state
The RAD state, whose values are listed in the description
of the rad_state_t type.
ssize_t rinfo_physmem
The amount of physical memory present in the RAD.
ssize_t rinfo_freemem
The current amount of free memory available in the RAD.
cpuset_t rinfo_cpus
The set of CPUs associated with the RAD.
See rad_get_info(3) for more information about querying RAD
information.
rad_state_t
A RAD's software state. The defined states are:
RAD_ONLINE
The specified RAD exists and is on line. Processes and threads
may be assigned to and memory allocated to the RAD.
RAD_OFFLINE
The specified 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.
rsrctype_t
An enumeration type that specifies the kind of resource with which
affinity is desired. Functions that perform NUMA topology queries and
resource binding pass rsrctype_t arguments along with rsrcdescr_t
descriptors to identify resources. The following symbolic values
identify the type of resource being specified by a particular
descriptor:
R_RAD
A RAD set.
R_FILDES
A file or device referenced by an open file descriptor.
R_PATH
A file or device specified by a pathname.
R_SHM
A System V shared memory segment that is referenced by a shared
memory ID.
R_PID
A process that is referenced by a pid_t identifier.
R_MEM
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 particular memory
location. See nloc(3).
R_NSG
A NUMA Scheduling Group that is referenced by an nsgid_t
identifier.
rsrcdescr_t
A union of the various resource handles, or descriptors, that are
specified by different resource type (rsrctype_t) values. Along with an
rsrctype_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:
radset_t rd_radset
If the rsrctype_t value is R_RAD, a RAD set is the
resource, for which rd_radset is the handle.
int rd_fd 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.
char *rd_pathname
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.
int rd_shmid
If the rsrctype_t value is R_SHM, a System V shared memory
segment is the resource, for which rd_shmid is the handle.
pid_t rd_pid
If the rsrctype_t value is R_PID, a process is the
resource, for which rd_pid is the handle.
void *rd_addr
If the rsrctype_t value is R_MEM, a mapped region of
virtual memory is the resource, for which rd_addr is the
handle.
nsgid_t rd_nsg
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 system
topology.
struct_nsgid_ds
A structure that specifies the access permissions and associated
parameters and statistics for a NUMA Scheduling Group (NSG). This
structure contains the following members:
struct ipc_perm nsg_perm
A subordinate structure that contains the NSG access
permissions.
int nsg_nattach
The number of processes attached to the NSG.
struct_nsg_thread
A structure that specifies a thread (process ID and thread ID) attached
to an NSG. This structure contains the following members:
pid_t nsgth_pid
The process ID of a thread that is attached to an NSG.
unsigned int nsgth_thread
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)
|
Index for
Section 4 |
|
|
Alphabetical
listing for N |
|
 |
Top of
page |
|