pthread_nsg_attach(3)pthread_nsg_attach(3)NAMEpthread_nsg_attach - Attaches a thread to a NUMA Scheduling Group
(libpthread library)
SYNOPSIS
#include <numa.h>
int pthread_nsg_attach(
nsgid_t nsg,
pthread_t thread,
long flags );
PARAMETERS
Specifies the NUMA Scheduling Group (NSG) to which the thread will
belong. Identifies the thread to attach to the NSG. Specifies options
(bit mask) that affect the attachment. See DESCRIPTION for details.
DESCRIPTION
The pthread_nsg_attach() function attaches the thread specified by the
thread argument to a NUMA Scheduling Group (NSG) specified by the nsg
argument. An NSG is a set of processes and/or threads that will be con‐
strained to reside on the same Resource Affinity Domain (RAD). That is,
the “home RAD” for all of the processes/threads in an NSG will be the
same, and the entire group will be migrated together, if at all. The
thread specified by thread will be removed from any NSG of which it
might currently be a member, before being added to the specified NSG.
If the specified thread resides on a different RAD, the thread will be
reassigned to a single RAD. The home RAD for the thread will be
selected as follows: If the specified NSG already has processes/threads
attached, the home RAD for the specified thread will be the home RAD
for that NSG. If the specified NSG is empty, the home RAD for the
thread will be selected based on the setting of the flags argument.
The following options are defined for the flags argument: The requested
attachment and any implied reassignments are mandatory, overriding any
prior binding of the specified thread. If this option is not set, and
the thread is bound (RAD_INSIST) to a different RAD such that the sys‐
tem cannot honor the request, the request will fail. The thread has
small memory requirements, so the system should favor (for the home
RAD) those RADs with light CPU loads, independent of their available
memory. This flag applies only when attaching to an empty NSG. The
thread has large memory requirements, so the system should favor (for
the home RAD) those RADs with more available memory, independent of
their CPU loads. This flag only applies when attaching to an empty NSG.
Arrange for the existing memory (stack pages) of a thread that is
assigned a new home RAD to be migrated to the new RAD. If omitted, only
newly allocated pages will be allocated on the new home RAD. Existing
pages will migrate if/when they experience a high rate of remote cache
misses. Migration will occur only for pages-in-memory objects that have
inherited the process's default memory allocation policy. Wait for the
requested memory migration to be completed. Effectively, this flag
specifies “migrate now!”.
RETURN VALUES
Success. Failure. In this case, the returned integer indicates the
type of error. Possible errors include the following: The caller does
not have execute permission required to attach the thread based on the
NSG's permissions. The thread specified by thread is hard attached
(RAD_INSIST) to RADs or has memory wired (locked) on its current RAD
such that it cannot be migrated to the common RAD selected for the NSG.
The value of the flags argument is invalid. NSG_INSIST and NSG_MIGRATE
were specified and no RAD can be found with sufficient memory to accom‐
modate the resulting group. The thread specified by the thread argu‐
ment does not exist.
ERRORS
None.
SEE ALSO
Functions: nsg_attach_pid(3), nsg_get(3), numa_intro(3)
Files: numa_types(4)pthread_nsg_attach(3)
