pset_assign(2)

NAME

pset_assign() — change processor set assignment

SYNOPSIS

#include <sys/pset.h>

int pset_assign( 
psetid_t pset,
spu_t spu,
psetid_t *opset
);

DESCRIPTION

The pset_assign() function assigns the processor spu to the processor set pset, removing the processor spu from its current processor set. A processor may not belong to more than one processor set at any given time. If opset is not NULL, it contains the processor set ID of the previously assigned processor set upon successful operation.

A user with the PSET privilege or a user with WRITE permissions on the processor sets may change the processor set assignment for a processor using the pset_assign() function. A user without the PSET privilege must have WRITE permissions in both processor sets to make the processor reassignment, unless the target processor set is the system default processor set. That is, only a user with the PSET privilege may move a processor out of the system default processor set.

Currently, processor 0 cannot be reassigned to another processor set from the system default processor set. The system default processor set is never empty.

If pset is PS_DEFAULT or PS_NONE, the processor spu is assigned to the system default processor set.

If pset is PS_QUERY, the processor's assignment is not changed, but the current processor set ID of processor spu is returned in opset. Neither WRITE permission nor the PSET privilege is needed for PS_QUERY operation.

If there are threads or processes with binding to the processor spu (in its old processor set), the binding of affected threads and processes is changed to another processor in that processor set. If spu is the last processor in the locality domain that contributes to its current processor set and there are threads or processes with binding to the locality domain, their binding is changed to another locality domain in the processor set. See mpctl(2) for binding to processors and locality domains.

If spu is the last processor in its current processor set, the behavior of pset_assign() is dependent on the value of the PSET_ATTR_LASTSPU attribute. The following attribute values are defined for this attribute:

PSET_ATTRVAL_DFLTPSET: Assign the processor to the specified processor set, and migrate all threads and processes to the system default processor set, PS_DEFAULT. This is the default behavior. If the threads and processes being migrated to the system default processor set (pset) have binding to processor or locality domain, their binding is reassigned to another processor or locality domain in the system default processor set.
PSET_ATTRVAL_FAIL: Make the request fail if there are active threads and processes assigned to the processor set.

Security Restrictions

Some or all of the actions associated with this system call require the PSET privilege. Processes owned by the superuser have this privilege. Processes owned by other users may have this privilege, depending on system configuration. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

Note on Logical Processor and Hyper-Threading Feature

On systems with the Hyper-Threading (HT) feature enabled at the firmware, each hyper-thread is represented as a logical processor (LCPU).

For pset_assign(), migration of a logical processor in a processor core may also migrate that logical processor's sibling logical processor, which belongs to the same physical processor core. Otherwise the resulting configuration would violate the processor set contract, which specifies that applications bound to a processor set have complete and exclusive control of all processor cores within that processor set.

When a processor core is assigned to another pset, depending on the source and target processor sets' PSET_ATTR_LCPU (see pset_setattr(2)) value, the number of logical processors from that processor core may change.

EXAMPLES

Reassign spu from its current processor set to new_pset, and retrieve the current processor set in old_pset.

#include  <sys/pset.h> 

spu_t     spu; 
psetid_t  new_pset, old_pset; 
int       ret; 

/* 
 * Initialize spu and new_pset first. 
 * spu identifies the processor to be reassigned, whereas 
 * new_pset identifies the target processor set. 
 */ 
if ((ret = pset_assign(new_pset, spu, &old_pset)) < 0) { 
perror("pset_assign"); 
    exit(1); 
} 

RETURN VALUE

pset_assign returns zero on successful completion. Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS

pset_assign fails if one or more of the following is true:

EBUSY: The processor set currently assigned to the processor spu has active threads and processes, and the processor set attributes do not allow this operation.
EFAULT: The memory location pointed to by opset is not writable by the user.
EINTR: The operation was interrupted.
EINVAL: The processor spu or processor set pset is not valid.
EINVAL: The spu is not enabled.
EINVAL: The memory location pointed to by opset is NULL, and the PS_QUERY operation is requested.
ENOSYS: The processor set functionality is not supported by the underlying HP-UX version.
EPERM: The user does not have necessary permissions to assign spu to pset.

pset_assign(2)

Technical documentation

» Table of Contents

» Index