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:
- If psid is set to
PS_QUERY
, then the current processor set ID
will be returned into psid, and no assignment
will be performed.
- If psid is set to
PS_MYID
, then the processor set ID of the
calling process will be used, and psid will be
ignored.
- 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:
- 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.
- If psid is set to
PS_MYID
, then the processor set ID of the
calling process will be used.
- 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.