PSET(3)

PSET(3) | Library Functions Manual | PSET(3)

# NAME

`pset_create`, `pset_assign`, `pset_bind`, `pset_destroy` —
processor sets

# SYNOPSIS

`#include <sys/pset.h>`

int
`pset_create`(psetid_t *psid);

int
`pset_assign`(psetid_t psid, cpuid_t cpuid, psetid_t *opsid);

int
`pset_bind`(psetid_t psid, idtype_t type, id_t id, psetid_t *opsid);

int
`pset_destroy`(psetid_t psid);

# DESCRIPTION

The processor sets API provides the possibility to exclusively dedicate specific processors or groups of processors to processes or threads. After processes or threads are bound to a group of processors by the API, the group henceforth runs only those processes or threads. This section describes the functions used to control processor sets.

# FUNCTIONS

`pset_create`(psid)
  Creates a processor set, and returns its ID into psid.
`pset_assign`(psid, cpu, opsid)
  Assigns the processor specified by cpuid to the processor set specified by psid. Stores the current processor set ID of the processor or `PS_NONE` into opsid, if the pointer is not `NULL`.

  The following actions can be specified:

  1. If psid is set to `PS_QUERY`, then the current processor set ID will be returned into psid, and no assignment will be performed.
  2. If psid is set to `PS_MYID`, then the processor set ID of the calling process will be used, and psid will be ignored.
  3. If psid is set to `PS_NONE`, any assignment to the processor will be cleared.
`pset_bind`(psid, type, id, opsid)
  Dedicates the processor set specified by psid to the target specified by id. The current processor set ID to which the target is bound or `PS_NONE` will be returned in opsid, if the pointer is not `NULL`. NetBSD supports the following types of targets specified by type:
  `P_PID`
    Process identified by the PID.
  `P_LWPID`
    Thread of the calling process indentified by the LID.

  The following actions can be specified:

  1. If psid is set to `PS_QUERY`, then the current processor set ID to which the target is bound or `PS_NONE` will be returned in opsid, and no binding will be performed.
  2. If psid is set to `PS_MYID`, then the processor set ID of the calling process will be used.
  3. If psid is set to `PS_NONE`, the specified target will be unbound from the processor set.
`pset_destroy`(psid)
  Destroys the processor set specified by psid. Before destroying the processor set, all related assignments of the processors will be cleared, and all bound threads will be unbound.

  If psid is `PS_MYID`, the processor set ID of the caller thread will be used.

# IMPLEMENTATION NOTES

The `pset_bind`() function can return the current processor set ID to which the target is bound, or `PS_NONE`. However, for example, the process may have many threads, which could be bound to different processor sets. In such a case it is unspecified which thread will be used to return the information.

There is an alternative thread affinity interface, see affinity(3). However, processor sets and thread affinity are mutually exclusive, hence mixing of these interfaces is prohibited.

# RETURN VALUES

Upon successful completion these functions return 0. Otherwise, -1 is returned and errno is set to indicate the error.

# EXAMPLES

An example of code fragment, which assigns the CPU whose ID is 0, for current process:

    	psetid_t psid;
    	cpuid_t ci = 0;

    	if (pset_create(&psid) < 0)
    		err(EXIT_FAILURE, "pset_create");

    	/* Assign CPU 0 to the processor-set */
    	if (pset_assign(psid, ci, NULL) < 0)
    		err(EXIT_FAILURE, "pset_assign");

    	/* Bind the current process to the processor-set */
    	if (pset_bind(psid, P_PID, P_MYID, NULL) < 0)
    		err(EXIT_FAILURE, "pset_bind");

    	/*
    	 * At this point, CPU 0 runs only the current process.
    	 */
    	perform_work();

    	if (pset_destroy(psid) < 0)
    		err(EXIT_FAILURE, "pset_destroy");

# ERRORS

The `pset_create`() function fails if:

[`ENOMEM`]
  No memory is available for creation of the processor set, or limit of the allowed count of the processor sets was reached.
[`EPERM`]
  The calling process is not the super-user.

The `pset_assign`() function fails if:

[`EBUSY`]
  Another operation is performing on the processor set.
[`EINVAL`]
  psid or cpuid are invalid.
[`EPERM`]
  The calling process is not the super-user, and psid is not `PS_QUERY`.

The `pset_bind`() function fails if:

[`EBUSY`]
  Another operation is performing on the processor set.
[`EINVAL`]
  psid or type are invalid.
[`EPERM`]
  The calling process is not the super-user, and psid is not `PS_QUERY`.
[`ESRCH`]
  The specified target was not found.

The `pset_destroy`() function fails if:

[`EBUSY`]
  Another operation is performing on the processor set.
[`EPERM`]
  The calling process is not the super-user.

# SEE ALSO

affinity(3), cpuset(3), sched(3), schedctl(8)

# STANDARDS

This API is expected to be compatible with the APIs found in Solaris and HP-UX operating systems.

# HISTORY

The processor sets appeared in NetBSD 5.0.

May 6, 2010 | NetBSD 9.5