nfork(3)nfork(3)NAMEnfork - Creates a child process (libnuma library)
SYNOPSIS
#include <numa.h>
pid_t nfork(
numa_attr_t *numa_attr );
PARAMETERS
Points to a structure of type numa_attr_t that contains the following
members: The type of resource to which the child process will be
attached, or near which the child process will be located. The
resource descriptor for the resource to which the child process will be
attached, or near which the child process will be located. The dis‐
tance criteria for selecting resources. RADs in the caller's partition
that have a distance (from the specified resource) equal to or less
than this value will be considered as candidates for the child
process's location. A bit mask of options that help control how the
system assigns a “home RAD” to the child process.
The following symbolic values are defined for this bit mask: The
requested RAD assignment is mandatory. The child process will be
created on one of the RADs in the specified RAD set regardless
of the CPU or memory load of the specified RADs. The child
process might not be assigned to the same home RAD as its parent
process. 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. The process has “small mem‐
ory” requirements, so the system should favor (for the child
process's 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 child
process's home RAD) those RADs with more available memory, inde‐
pendent of CPU loads.
If numa_attr is NULL, the function behaves as fork().
DESCRIPTION
The nfork() function causes creation of a new process. The new process
(child process) is an exact copy of the calling process (parent
process). This means the child process inherits the following
attributes from the parent process: Environment Close-on-exec flag. See
exec(2). Signal-handling settings (in other words, SIG_DFL, SIG_IGN,
SIG_HOLD, function address) Set-user-ID mode bit Set-group-ID mode bit
Trusted state Profiling on/off status Nice value. See nice(2). All
attached shared libraries Process group ID Session ID (tty group ID)
Foreground process ID. See exit(2). Current working directory Root
directory File mode creation mask. See umask(2). File size limit. See
ulimit(2). All attached shared memory segments. See shmat(2). All
attached mapped regions. See mmap(2) and nmmap(3). All mapped regions
with the same protection and sharing mode as in the parent process.
The child process differs from the parent process in the following
ways: The child process has a unique process ID that does not match any
active process group ID. The parent process ID of the child process
matches the process ID of the parent. The child process has its own
copy of the parent process's file descriptors. Each of the child's file
descriptors refers to the same open file description with the corre‐
sponding file descriptor of the parent process. The child process has
its own copy of the parent's open directory streams. Each open direc‐
tory stream in the child process may share directory stream positioning
with the corresponding directory stream of the parent. All semadj val‐
ues are cleared. Process locks, text locks and data locks are not
inherited by the child. See plock(2). The child process's values of
tms_utime, tms_stime, tms_cutime, and tms_cstime are set to 0. Any
pending alarms are cleared in the child process. Any interval timers
enabled by the parent process are reset in the child process. Any sig‐
nals pending for the parent process are cleared for the child process.
The NUMA scheduling parameters and memory allocation attributes of the
child process may be different from those of the parent process.
The nfork() function is used when the caller wishes to specify the
location where the child process should be loaded. If the nattr_descr
field is NULL, the nfork() function behaves identically to the fork()
function, and the child process inherits the calling thread's memory
allocation policy and attributes. However, the nattr_flags field may
still affect how the system selects a home RAD for the child process,
as described in PARAMETERS.
If the nattr_descr field is non-NULL, it, along with the nattr_type and
nattr_distance fields, identifies the acceptable RADs from which to
select the child process's home RAD. The memory allocation policy for
the child process will be set to MPOL_THREAD.
If nattr_type is anything other than R_RAD or R_NSG, nfork() will
behave as though nloc() were called to obtain a RAD set that meets the
specified criteria, and then nfork() were called with nattr_type equal
to R_RAD, and nattr_descr pointing to the RAD set returned by nloc().
This behavior is described below. The nattr_distance parameter is
ignored for a nattr_type of R_RAD or R_NSG.
If the nattr_descr field is equal to R_RAD, then nattr_descr points to
a radset_t that identifies the acceptable RADs from which to select the
child process's initial home RAD. The remainder of the RAD set (in
other words, the set less the child process's home RAD) becomes the
child's overflow set.
A suitable set of RADs can be located according to available resources
by nloc() and can be manipulated using the operators described for rad‐
setops(). Unless RAD_INSIST has been set in nattr_flags, the specified
RAD set is considered a hint, which may be overridden if all the RADs
in the specified set have very high CPU loads or too little available
memory. If the RAD_INSIST flag is specified in nattr_flags, the RAD
specification is treated as mandatory, and the child process is
assigned to one of the specified RADs despite a large CPU load or mem‐
ory shortage.
When using nfork(), the caller can further specify an appropriate RAD
by setting the RAD_SMALLMEM or RAD_LARGEMEM bits in the nattr_flags
field. RAD_SMALLMEM indicates that the child will have very low memory
requirements, so can be placed on a RAD having little available memory
if that RAD has a particularly light CPU load. Conversely, if
RAD_LARGEMEM is set, the process is placed on the RAD with the most
available memory even though that RAD may have a high CPU load.
RAD_SMALLMEM and RAD_LARGEMEM are also taken into account during any
future process migrations.
If the nattr_descr field is equal to R_NSG, then nattr_descr specifies
a NUMA Scheduling Group (NSG) as returned by nsg_init(). The child
process will be attached to the NSG and will receive the same home RAD
as the other members in the NSG. If the child process is the first
process to attach to the NSG, then the home RAD for the child will be
inherited from the calling thread, just as for the fork() function.
NOTES
The nfork() function is supported for multithreaded applications.
If a multithreaded process calls the nfork() function, the new process
contains a replica of the calling thread and its entire address space,
possibly including the states of mutexes and other resources. Conse‐
quently, to avoid errors, the child process should only execute opera‐
tions that will not cause deadlock until one of the exec functions is
called.
The set of valid resources that may be specified is constrained by the
caller's partition.
RETURN VALUES
Success (returned to the child process). In this case, the function
also returns the process ID of the child process to the parent process.
The child process and all of the related data structures will be allo‐
cated on one of the RADs selected by the system scheduler from among
those specified by the nattr_type, nattr_descr, and nattr_distance
fields. The initial thread of the child process will be scheduled on
one of the available CPUs in the selected RAD. Failure (returned to
the parent process). In this case, no child process is created, and
errno is set to indicate the error.
ERRORS
If the nfork() function fails, it sets errno to one of the following
values for the condition specified: The limit on the total number of
processes executing for a single user would be exceeded. This limit can
be exceeded by a process with superuser privilege. The numa_attr argu‐
ment or the nattr_descr structure field points to an invalid address.
The nattr_type field specifies an invalid resource type, the
nattr_descr field specifies an invalid resource, or the nattr_flags
field specifies an undefined flag. There is not enough memory to cre‐
ate the child process.
SEE ALSO
Functions: exec(2), exit(2), fork(2), mmap(2), plock(2), umask(2),
nice(3), nloc(3), nmmap(3), nsg_init(3), numa_intro(3), radsetops(3),
ulimit(3)
Files: numa_types(4)nfork(3)