Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

nsg_init(3) [osf1 man page]

nsg_init(3)						     Library Functions Manual						       nsg_init(3)

NAME
nsg_init - Look up or create a NUMA Scheduling Group (libnuma library) SYNOPSIS
#include <numa.h> nsgid_t nsg_init( key_t key, ulong_t flags ); PARAMETERS
Specifies the key that identifies the NUMA Scheduling Group (NSG). This value may be one of the following: An arbitrary binary value other than zero If the NSG_GETBYPID flag is set, the process ID of a member process of the requested NSG Specifies lookup or creation flags. See DESCRIPTION for details. DESCRIPTION
The nsg_init() function looks up and possibly creates the NSG identified by the key parameter. The flags parameter supplies options for the lookup or create operation. If the flags parameter includes the NSG_GETBYPID flag, then the key parameter is the process ID (pid_t) of a process that is currently a member of the requested NSG. Otherwise, key is an arbitrary binary value that identifies the requested NSG. If the NSG identified by key does not already exist, an error will be returned unless the NSG_CREATE flag is specified. The NSG_CREATE flag instructs nsg_init() to create the NSG and return its identifier. If NSG_CREATE and NSG_EXCL are both specified, an error will be returned if the NSG identified by key already exists. If the NSG_GETBYPID flag is set and the process identified by the value of key does not exist, an error is returned. If the NSG_CREATE flag is set along with the NSG_GETBYPID flag, and the process identified by the value of key exists but is not currently a member of an NSG, a new NSG will be created using the value of key (the process's ID) and the process will be attached to the new NSG. This establishes the "home RAD" of the process as the home RAD for the NSG. After creating a new NSG, the nsg_init() function initializes an associated nsgid_ds structure as follows: The nsg_perm.cuid and nsg_perm.uid members are set equal to the effective user ID of the calling process. The nsg_perm.cgid and nsg_perm.gid members are set equal to the effective group ID of the calling process. The low order nine bits of nsg_perm.mode are set equal to the low order nine bits of flags. The nsg_perm.nattach member is set to zero (or 1 if NSG_GETBYPID is specified in flags). The nsg_perm.mode permissions control operations on NSGs as follows: Write permission is required to destroy the NSG or to set the owner IDs and permissions. Read permission is required to query the NSG status or membership roster. Execute permission is required to attach processes or threads to an NSG. If NSG_CLEANUP is specified in flags, the NSG will be marked for automatic deletion when the nsg_perm.nattach member of the associated nsgid_ds structure transitions from non-zero to zero. RETURN VALUES
Success. Failure. In this case, errno is set to indicate the error. ERRORS
If the nsg_init() function fails, it sets errno to one of the following values for the specified condition: An NSG already exists for the specified key, but the caller does not have access based on the NSG's current permissions. An NSG already exists for the specified key, but NSG_CREATE and NSG_EXCL flags were specified. No NSG exists for the specified key, and the NSG_CREATE flag was not specified. The NSG_GETBYPID flag was set and the process identified by key was not found. One or more illegal values for flags was set. SEE ALSO
Functions: nsg_attach_pid(3), nsg_attach_thread(3), numa_intro(3) Files: numa_types(4) nsg_init(3)

Check Out this Related Man Page

nfork(3)						     Library Functions Manual							  nfork(3)

NAME
nfork - 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 distance 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. 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. The process has "small memory" 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 require- ments, so the system should favor (for the child process's home RAD) those RADs with more available memory, independent 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 cor- responding file descriptor of the parent process. The child process has its own copy of the parent's open directory streams. Each open directory stream in the child process may share directory stream positioning with the corresponding directory stream of the parent. All semadj values 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 inter- val timers enabled by the parent process are reset in the child process. Any signals 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 radsetops(). 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. Consequently, to avoid errors, the child process should only execute operations 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 allocated 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 argument 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)
Man Page