rad_attach_pid(3)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 sys‐
tem scheduler 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 privi‐
lege.) 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 can be assigned to any RAD on the
system, and might not inherit its parent's home RAD assignment; that
is, the child processes might not be assigned to the same home RAD as
the parent. This allows the system to assign a home RAD to the child
process depending on available resources.
Normally, child processes do inherit the assignments and
attributes of the parent process.
By default, processes that are later forked by the process spec‐
ified 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 consider 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 mem‐
ory 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 sys‐
tem should favor (for the home RAD) those RADs with more avail‐
able memory, independent of their CPU loads. Arrange for exist‐
ing 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. Effec‐
tively, 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 speci‐
fied: 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 appropri‐
ate 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)