rs_setpartition Subroutine

Edit online

Purpose

Sets the partition resource set of a process.

Library

Standard C library (libc.a)

Syntax

include <sys/rset.h>

int rs_setpartition(pid, rset, flags)
pid_t pid;
rsethandle_t rset;
unsigned int flags;

Description

The rs_setpartition subroutine sets a process' partition resource set. The subroutine can also be used to remove a process' partition resource set.

The partition resource set limits the threads in a process to running only on the processors contained in the partition resource set.

The work component is an existing process that is identified by the process ID. A process ID value of RS_MYSELF indicates that the attachment applies to the current process.

The following conditions must be met to set a process' partition resource set:
  • The calling process must have root authority.
  • The resource set must contain processors that are available in the system.
  • The new partition resource set must be equal to, or a superset of the target process' effective resource set.
  • The target process must not contain any threads that have bindprocessor bindings to a processor.
  • The resource set must be a superset of all the threads' rset in the target process.
The flags parameter can be set to indicate the policy for using the resources that are 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 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 the R_ATTACH_STRSET flag is specified, then all of the available processors that are 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

Table 1. Parameters
Item Description
pid Specifies the process ID of the process whose partition resource set is to be set. A value of RS_MYSELF indicates the current process' partition resource set should be set.
rset Specifies the partition resource set to be set. A value of RS_DEFAULT indicates the process' partition resource set should be removed.
flags Specifies the policy to use for the process. A value of R_ATTACH_STRSET 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 rs_setpartition subroutine is unsuccessful if one or more of the following are true:
Table 2. Error Codes
Item Description
EINVAL 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 that is identified by the pid parameter does not exist.
EFAULT Invalid address.
ENOMEM Memory is not available.
EPERM One of the following is true:
  • The calling process does not have root authority.
  • The process that is identified by the pid parameter has one or more threads with a bindprocessor processor binding.
  • The process that is identified by the pid parameter has an effective resource set and the new partition resource set identified by the rset parameter does not contain all of the effective resource set's resources.
  • One of the threads in the process that is identified by the pid parameter has a thread level resource set, and the new partition resource set identified by the rset parameter does not contain all of the thread level resource set's resources.