ra_attachrset Subroutine

Purpose

Attaches a work component to a resource set.

Library

Standard C library (libc.a)

Syntax

#include <sys/rset.h>
int ra_attachrset (rstype, rsid, rset, flags)
rstype_t rstype;
rsid_t rsid;
rsethandle_t rset;
unsigned int flags;

Description

The ra_attachrset subroutine attaches a work component specified by the rstype and rsid parameters to a resource set specified by the rset parameter.

The work component is an existing process identified by the process ID or an existing kernel thread identified by the kernel thread ID (tid). A process ID or thread ID value of RS_MYSELF indicates the attachment applies to the current process or the current kernel thread, respectively.

The following conditions must be met to successfully attach a process to a resource set:

The resource set must contain processors that are available in the system.
The calling process must either have root authority or have CAP_NUMA_ATTACH capability.
The calling process must either have root authority or the same effective userid as the target process.
The target process must not contain any threads that have bindprocessor bindings to a processor.
The resource set must be contained in (be a subset of ) the target process' partition resource set.
The resource set must be a superset of all the threads' rset in the target process.
For R_FILDES rstype, the calling process must specify an open file descriptor, and it must have write access to the file, or the calling process' effective userid must be equal to the file owner's userid.
For R_SHM rstype, the calling process' effective userid must be equal to the shared segment's owner.

The following conditions must be met to successfully attach a kernel thread to a resource set:

The resource set must contain processors that are available in the system.
The calling process must either have root authority or have CAP_NUMA_ATTACH capability.
The calling process must either have root authority or the same effective userid as the target process.
The target thread must not have bindprocessor bindings to a processor.
The resource set must be contained in (be a subset of ) the target thread's process effective and partition resource set.

If any of these conditions are not met, the attachment will fail.

Once a process is attached to a resource set, the threads in the process will only run on processors contained in the resource set. Once a kernel thread is attached to a resource set, the threads will only run on processors contained in the resource set.

Dynamic Processor Deallocation and DLPAR may invalidate the processor attachment that is being specified. A program must become DLPAR Aware to resolve this problem.

The flags parameter can be set to indicate the policy for using the resources contained in the resource set specified in the rset parameter. The only supported scheduling policy is R_ATTACH_STRSET, which is useful only when the processors of the system are running in simultaneous multithreading mode. Processors like the POWER5 support simultaneous multithreading, where each physical processor has two execution engines, called hardware threads. Each hardware thread is essentially equivalent to a single processor, and each is identified as a separate processor in a resource set. The R_ATTACH_STRSET flag indicates that the process is to be scheduled with a single-threaded policy; namely, that it should be scheduled on only one hardware thread per physical processor. If this flag is specified, then all of the available processors indicated in the resource set must be of exclusive use (the processor must belong to some exclusive use processor resource set). A new resource set, called an ST resource set, is constructed from the specified resource set and attached to the process according to the following rules:

All offline processors are ignored.
If all the hardware threads (processors) of a physical processor (when running in simultaneous multithreading mode, there will be more than one active hardware thread per physical processor) are not included in the specified resource set, the other processors of the processor are ignored when constructing the ST resource set.
Only one processor (hardware thread) resource per physical processor is included in the ST resource set.

Parameters

Item	Description
rstype	Specifies the type of work component to be attached to the resource set specified by the rset parameter. The rstype parameter must be the following value, defined in rset.h: R_PROCESS Existing process R_THREAD Existing kernel thread R_FILDES File identified by an open file descriptor R_SHM Shared memory segment identified by shared memory segment ID R_SUBRANGE Attachment involves a subrange of the work component
rsid	Identifies the work component to be attached to the resource set specified by the rset parameter. The rsid parameter must be the following: Process ID (for rstype of R_PROCESS) Set the rsid_t at_pid field to the desired process' process ID. Kernel thread ID (for rstype of R_THREAD) Set the rsid_t at_tid field to the desired kernel thread's thread ID. Open file descriptor (for rstype of R_FILDES) Set the rsid_t at_fd field to the desired file descriptor. Shared memory segment ID (for rstype of R_SHM) Set the rsid_t at_shmid field to the desired shared memory ID. Pointer to a subrange_t struct (for rstype of R_SUBRANGE) Set the subrange_t su_offset, su_length, su_rstype, and su_rsid fields. The other fields in the subrange_t struct are ignored. The memory allocation policy is taken from the flags parameter, not the su_policy field.
rset	Specifies which work component (specified by the rstype and rsid parameters) to attach to the resource set.
flags	Specifies either the memory allocation or the scheduling policy for the work component being attached. The flags parameter must be the following: P_DEFAULT Default memory policy P_FIRST_TOUCH First access memory policy P_BALANCED Balanced memory policy R_ATTACH_STRSET Single-threaded scheduling policy If the rstype parameter value is set to R_SUBRANGE, the memory allocation policy is specified in the subrange_t su_policy field rather than in the flags parameter. The R_ATTACH_STRSET value is only applicable if the rstype parameter value is set to R_PROCESS. The R_ATTACH_STRSET value indicates that the process is to be scheduled with a single-threaded policy (only on one hardware thread per physical processor).

Return Values

If successful , a value of 0 is returned. If unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The ra_attachrset subroutine is unsuccessful if one or more of the following are true:

Item	Description
EINVAL	One of the following is true: The flags parameter contains an invalid value. The rstype parameter contains an invalid type qualifier. The R_ATTACH_STRSET flags parameter is specified and one or more processors in the rset parameter are not assigned for exclusive use.
ENODEV	The resource set specified by the rset parameter does not contain any available processors, or the R_ATTACH_STRSET flags parameter is specified and the constructed ST resource set does not have any available processors.
ESRCH	The process or kernel thread identified by the rstype and rsid parameters does not exist.
EPERM	One of the following is true: If the rstype is R_PROCESS, either the resource set specified by the rset parameter is not included in the partition resource set of the process identified by the rstype and rsid parameters, or any of the thread's R_THREAD rset in this process is not a subset of the resource set specified by the rset parameter. If the rstype is R_THREAD, the resource set specified by the rset parameter is not included in the target thread's process effective or partition (real) resource set. The calling process has neither root authority nor CAP_NUMA_ATTACH attachment privilege. The calling process has neither root authority nor the same effective user ID as the process identified by the rstype and rsid parameters. The process or thread identified by the rstype and rsid parameters has one or more threads with a bindprocessor processor binding.