rad_attach_pid(3) Library Functions Manual rad_attach_pid(3)
NAME
rad_attach_pid, rad_bind_pid - Attaches or binds a process to a Resource Affinity Domain by process ID (libnuma library)
SYNOPSIS
#include <numa.h>
int rad_attach_pid(
pid_t pid,
radset_t radset,
ulong_t flags ); int rad_bind_pid(
pid_t pid,
radset_t radset,
ulong_t flags );
PARAMETERS
Identifies the process to be attached or bound to the specified set of Resource Affinity Domains (RADs). Specifies the RAD set to which
the process will be attached or bound. Specifies options (a bit mask) that affect the attachment or binding operation. See DESCRIPTION for
details.
DESCRIPTION
The rad_attach_pid() function attaches the process specified by pid to the set of RADs specified by radset.
The rad_bind_pid() function binds the process specified by pid to the set of RADs specified by radset.
While both functions assign a "home" RAD for the process, an attach operation allows remote execution on other RADs while a bind operation
restricts execution to the "home" RAD. For both functions, if the pid argument is NULL, the call is self-directed. That is, the function
behaves as if pid identified the calling process.
The memory allocation policy for the process will be set to MPOL_THREAD. The home RAD for the process will be selected by the system sched-
uler from among the RADs included in radset and will be based on current system load balance and the flags argument. The overflow set
(mattr_radset) for the process will be set to radset. If the process has multiple threads, then any of those threads that have inherited
the process's default memory allocation policy will be attached or bound by using the same new memory allocation policy as used for the
process that contains them.
The threads of the specified process will be scheduled on one of the CPUs associated with the selected RAD, except for threads that have
been explicitly bound to some other processor. The CPU will be selected by the scheduler from among those CPUs associated with the
selected RAD in the process's partition. (This partition might not be the same as the caller's partition if the caller has appropriate
privilege.) The selection will be determined by the loading of the CPUs.
The following options are defined for the flags argument: Any processes later forked by the specified process will inherit its home RAD
assignment; that is, the child processes will be assigned to the same home RAD as their parent process. If the parent process was attached,
the child processes will be attached. If the parent process was bound, the child processes will be bound.
By default, processes that are later forked by the process specified in a rad_attach_pid() or rad_bind_pid() call inherit the RAD
assignment of their parent. The requested attachments or bindings are mandatory. If this option is not set, the system will con-
sider the request to be a "hint" and may take no action for the specified process or, if applicable, any child processes that the
specified process contains. The process has small memory requirements, so the system should favor (for the home RAD) those RADs
with light CPU loads, independent of their available memory. The process has large memory requirements, so the system should favor
(for the home RAD) those RADs with more available memory, independent of their CPU loads. Arrange for existing memory of the
process to be migrated to the new home RAD. If RAD_MIGRATE is omitted, only newly allocated pages will be allocated on the new home
RAD. Existing pages will migrate if or 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 specifies "migrate now!".
If the caller does not have partition administration privilege and if pid is not in the caller's partition, or if the radset argument con-
tains RADs that are not in the caller's partition, an error will be returned.
The value for the radset argument could be obtained from a prior call to nloc() that assigned or migrated the process to a RAD close or
closer to a particular resource. When obtained this way, radset will contain only the RADs in the caller's partition at the time of the
nloc() call. The partition configuration could change between a call to nloc() and a subsequent call to rad_attach_pid() or rad_bind_pid(),
resulting in an error. This error is not likely to occur often, but a robust application should handle it.
RETURN VALUES
Success. Failure. In this case, the functions set errno to indicate the error.
ERRORS
If either of these functions fail,
errno is set to one of the following values for the condition specified: RAD_INSIST and RAD_MIGRATE were specified and the specified
process cannot be migrated for some reason. For example, memory is wired (locked) on the process's current RAD. The radset argument points
to an invalid address. One or more of the RADs in the radset argument or options in the flags argument are invalid. RAD_INSIST and
RAD_MIGRATE were specified and the specified process cannot be migrated because insufficient memory exists on the specified RAD set. The
real or effective user ID of the caller does not match the real or effective user ID of the specified process, or the caller does not have
appropriate privileges to assign processes to RADs. The process specified by pid does not exist.
SEE ALSO
Functions: nloc(3), rad_detach_pid(3)
rad_attach_pid(3)