pset_create(2)

NAME

pset_create() — create a processor set

SYNOPSIS

#include <sys/pset.h> 

int pset_create(psetid_t *newpset); 

DESCRIPTION

The pset_create() function creates an empty processor set with no processors. Processor sets allow a subset of processors in the system to be isolated for exclusive use by specified threads and processes. Only the threads bound to a processor set can execute on processors in that processor set. The binding of threads and processes to processor sets is controlled by the pset_bind() function (see pset_bind(2)).

A unique identifier is assigned to the new processor set created by the pset_create() function, and is returned to the caller in the memory location pointed to by newpset. This value is valid only if the function return value is zero.

A processor can be assigned to a processor set by the pset_assign() function. A processor may not belong to more than one processor set at a time. There may be an implementation dependent limit on the maximum number of processor sets that may exist (created and not destroyed) at any given time.

Any user may create a new processor set with the pset_create() function. However, special permissions are needed to populate a processor set with processors (see pset_assign(2)), to execute applications in a processor set (see pset_bind(2)), or to destroy a processor set (see pset_destroy(2)). There may be a per user limit on how many processor sets that users without the PSET privilege may own.

Every processor set is assigned ownership and access permission attributes. The creator of a processor set becomes the default owner of the processor set.

The READ, WRITE, and EXEC access permissions are defined for processor sets for three access modes — Owner, Group, and Others — similar to the UNIX file system access permissions. The READ permission allows the caller to query about processor set configuration, the WRITE permission allows the caller to change processor set configuration and attributes, and the EXEC permission allows the caller to execute on processors in the processor set. The pset_setattr() function may be used to change the ownership and access permissions, whereas the pset_getattr() function may be used to query the current ownership and access permissions.

A system default processor set is created at system initialization time and cannot be destroyed. The default processor set is always owned by the user with UID 0 and has the processor set ID of PS_DEFAULT. Processor 0 is always assigned to the default processor set and cannot be reassigned to another processor set.

Note on Hyper-Threading

On systems with the hyper-threading capability enabled at the firmware level, each hyper-thread represents a logical processor (LCPU). Since the logical processors in the same physical processor core share common resources, interfaces dealing with workload migration or processor migration must operate at the physical processor core granularity.

The following is a list of processor set attributes and their default values at processor set creation time (see pset_getattr(2)):

PSET_ATTR_EMPTY: Indicates the behavior on a request to bind a process or a thread to a processor set that does not contain any processors. By default, such a request will be rejected.
PSET_ATTR_GRPID: GID of processor set's owner group. The creator's gid is assigned by default.
PSET_ATTR_IOINTR: A flag to indicate if processors in the set are configured to receive external I/O interrupts or not. All processors by default are made available to receive interrupts.
PSET_ATTR_LASTSPU: Indicates the behavior on a request to remove the last processor from a processor set. By default, all processes/threads assigned to the processor set are reassigned to the default processor set and the processor is reassigned as requested.
PSET_ATTR_LCPU: On a system with the hyper-threading feature enabled, the LCPU attribute indicates whether or not the processor cores in a processor set are enabled with logical processors (LCPU). By default, the default processor set's PSET_ATTR_LCPU attribute value is inherited at the time of creation. The non-default processor set's PSET_ATTR_LCPU can be modified by pset_setattr(), but the default processor set's PSET_ATTR_LCPU can only be modified by the dynamic kernel tunable command, kctune.
PSET_ATTR_NONEMPTY: Indicates the behavior on a request to destroy a non-empty processor set. The non-empty processor set refers to one that has at least one processor assigned to it. By default, all processors and processes/threads assigned to the processor set are reassigned to the system default processor set, and the processor set is destroyed.
PSET_ATTR_OWNID: UID of the processor set owner. The processor set creator is the default owner.
PSET_ATTR_PERM: Access permissions for the processor set. By default, the processor set owner has all permissions, whereas group and others have only READ and EXEC permissions.

Processor sets define a scheduling allocation domain for threads and processes. All threads may execute only on processors within the assigned processor set. The kernel load balancers work within the processor set boundary. There is no load balancing across the processor set boundary although users can explicitly migrate threads and processes from one processor set to another by using the pset_bind() function. The POSIX RTSCHED scheduler (see rtsched(2)) no longer works at the system level; its scheduling domain is restricted to the processor set boundary.

System daemon threads created in the kernel are not restricted to a user defined processor set configuration. They may run on any processor in the system as necessary.

Use sysconf() with _SC_PSET_SUPPORT to see if the processor set functionality is supported by the underlying HP-UX operating system version.

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.

EXAMPLES

Create a new processor set:

#include <sys/pset.h> 

psetid_t  new_psetid; 
int       ret; 

if ((ret = pset_create(&new_psetid)) < 0) { 
perror("pset_create()"); 
    exit(1); 
} 

RETURN VALUE

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

ERRORS

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

EAGAIN: The user has reached the per user limit on how many processor sets a user without the PSET privilege may own.
EFAULT: The memory location pointed to by newpset is not writable by the user.
EINVAL: The memory location pointed to by newpset is NULL.
EINVAL: Processor sets cannot be created on a uniprocessor system.
EPERM: The user does not have necessary permissions to create a new processor set.
ENOMEM: A new processor set cannot be created at this time due to lack of necessary system resources.
ENOSYS: The processor set functionality is not supported by the underlying HP-UX version.

pset_create(2)

Technical documentation

» Table of Contents

» Index