cpuset - overview of cpusets
DESCRIPTION
A cpuset is a named set of CPUs, which may be defined to
be restricted or open. A restricted cpuset only allows
processes that are members of the cpuset to run on the set
of CPUs. An open cpuset allows any process to run on its
cpus, but a process that is a member of the cpuset can
only run on the CPUs belonging to the cpuset.
A principal use of cpusets is to create a partition of
CPUs within a larger system. By doing this, a set of pro
cesses can be contained to specific CPUs, reducing the
amount of interaction those processes have with other work
on the system. In the case of a restricted cpuset, the
processes that are attached to that cpuset will not be
affected by other work on the system; only those processes
attached to the cpuset can be scheduled to run on the CPUs
assigned to the cpuset. An open cpuset can be used to
restrict processes to a set of CPUs so that the affect
these processes have on the rest of the system is mini
mized.
There are currently two methods in which to use cpusets:
the cpuset(1) command, and the cpuset library (see THE
CPUSET LIBRARY section below).
THE CPUSET COMMAND
The ccppuusseett command is used to create and destroy cpusets,
to retrieve information about existing cpusets, and to
attach a process and all of its children to a cpuset.
The ccppuusseett command uses a cpuset configuration file and a
name (see cpuset(4) for a definition of the file format).
The cpuset configuration file is used to define the CPUs
that are members of the cpuset. It also contains addi
tional parameters required to define the cpuset. A cpuset
name is between three and eight characters long; names of
two or less characters are reserved.
The file permissions of the configuration file define
access to the cpuset. When permissions need to be
checked, the current permissions of the file are used. It
is therefore possible to change access to a particular
cpuset without having to tear it down and recreate it,
simply by changing the access permissions. Read access
allows a user to retrieve information about a cpuset while
execute permission allows the user to attach a process to
the cpuset.
For additional information concerning the ccppuusseett command,
consult the cpuset(1) manual page.
The cpuset library provides interfaces that allow a pro
grammer to create and destroy cpusets, retrieve informa
tion about existing cpusets, to attach a process and all
of its children to a cpuset, and to attach or detach a
specific process identified by its PID to or from a
cpuset.
The cpuset library requires that a permission file be
defined for a cpuset that is created. The permissions
file may be an empty file, since it is only the file per
missions for the file that define access to the cpuset.
When permissions need to be checked, the current permis
sions of the file are used. It is therefore possible to
change access to a particular cpuset without having to
tear it down and recreate it, simply by changing the
access permissions. Read access allows a user to retrieve
information about a cpuset while execute permission allows
the user to attach a process to the cpuset.
The cpuset library file is lliibbccppuusseett..ssoo, and it is nor
mally located in the directory //uussrr//lliibb. Users of the
library must include the ccppuusseett..hh header file which is
located in //uussrr//iinncclluuddee. The function interfaces provided
in the cpuset library are declared as optional interfaces
to allow for backwards compatibility as new interfaces are
added to the library.
The function interfaces within the cpuset library include:
cpusetCreate(3x)
Create a cpuset
cpusetAttach(3x)
Attach the current process to a cpuset
cpusetAttachPID(3x)
Attach a specific process to a cpuset
cpusetDetachAll(3x)
Detach all threads from a cpuset
ccppuusseettDDeettaacchhPPIIDD
Detach a specific process from a cpuset
cpusetDestroy(3x)
Destroy a cpuset
cpusetGetCPUCount(3x)
Obtain the number of CPUs configured on the system
cpusetGetCPUList(3x)
Get the list of all CPUs assigned to a cpuset
Get the name of the cpuset to which a process is
attached
cpusetGetNameList(3x)
Get a list names for all defined cpusets
cpusetGetPIDList(3x)
Get a list of all PIDs attached to a cpuset
cpusetGetProperties(3x)
Get various properties of an existing cpuset.
cpusetAllocQueueDef(3x)
Allocate a cpuset_QueueDef_t structure
cpusetFreeProperties(3x)
Release memory used by a cpuset_Properties_t struc
ture
cpusetFreeQueueDef(3x)
Release memory used by a cpuset_QueueDef_t struc
ture
cpusetFreeCPUList(3x)
Release memory used by a cpuset_CPUList_t structure
cpusetFreeNameList(3x)
Release memory used by a cpuset_NameList_t struc
ture
cpusetFreePIDList(3x)
Release memory used by a cpuset_PIDList_t structure
EXAMPLES
This example creates a cpuset named "myqueue" containing
CPUs 4, 8, and 12. The example uses the interfaces in the
cpuset library, //uussrr//lliibb//lliibbccppuusseett..ssoo to create the
cpuset.
#include <cpuset.h>
#include <stdio.h>
#include <errno.h>
#define PERMFILE "/usr/tmp/permfile"
int
main(int argc, char **argv)
{
cpuset_QueueDef_t *qdef;
char *qname = "myqueue";
FILE *fp;
/* Alloc queue def for 3 CPU IDs */
qdef = cpusetAllocQueueDef(3);
if (!qdef) {
perror("cpusetAllocQueueDef");
exit(1);
}
/* Define attributes of the cpuset */
qdef->flags = CPUSET_CPU_EXCLUSIVE
| CPUSET_MEMORY_LOCAL
| CPUSET_MEMORY_EXCLUSIVE;
qdef->permfile = PERMFILE;
qdef->cpu->count = 3;
qdef->cpu->list[0] = 4;
qdef->cpu->list[1] = 8;
qdef->cpu->list[2] = 12;
/* Request that the cpuset be created */
printf("Creating cpuset = %s\n", qname);
if (!cpusetCreate(qname, qdef)) {
perror("cpusetCreate");
exit(1);
}
/* Free memory for queue def */
printf("Finished with cpuset definition,"
" releasing memory\n");
cpusetFreeQueueDef(qdef);
return 0;
}
RESTRICTIONS
The methods cpusetDetachPID(3x), cpusetGetCPUList(3x),
cpusetGetName(3x), and cpusetGetPIDList(3x) are not yet
implemented.
A CPU can belong to at most one cpuset.
CPU 0 cannot belong to an EXCLUSIVE cpuset.
Only the superuser can create or destroy cpusets.
runon(1) can not run a command on a cpu that is part of a
cpuset unless the user has write or group write permission
to access the cpuset's configuration file (this restric
tion is not yet implemented -- runon is not yet so con
strained.)
The kernel does not enforce cpuset restriction directly.
Rather restriction is established by booting the kernel
with the optional boot command line parameter
cpumemset_minimal
Set to only include the first CPU and memory node. The
rest of the systems CPUs and memory then remain unused
until attached to using cpuset or some other such root
priviledged facility. The cpuset command and library sup
port ensure restriction among clients of cpusets, but not
from other processes.
There is no facility to list all processes in a cpuset.
There is no facility to detach all processes from a
cpuset.
There is no facility to move all processes out of a
cpuset.
Deleting a cpuset does not require that no processes are
attached to it, and does not affect any processes (or
descendents thereof) already attached.
While it is possible to determine if a given process is
running on a cpumemset entirely contained within a cpuset
(see the -C option), it is not possible to know whether
that process got there by some explicit request to attach
(-A) to that cpuset by name, or by some other mechanism.
The -C option will display the name of cpuset entirely
containing the specified processes cpumemset in either
case.
Not all of the Memory Policies, as described in cpuset(4)
are supported. See the RESTRICTIONS section on that man
ual entry.
SEE ALSO
cpuset(1), cpusetAllocQueueDef(3x), cpusetAttach(3x),
cpusetAttachPID(3x), cpusetCreate(3x), cpusetDestroy(3x),
cpusetDetachAll(3x), cpusetDetachPID(3x), cpuset
FreeCPUList(3x), cpusetFreeNameList(3x), cpuset
FreePIDList(3x), cpusetFreeProperties(3x), cpusetGetCPU
Count(3x), cpusetGetCPUList(3x), cpusetGetName(3x),
cpusetGetNameList(3x), cpusetGetPIDList(3x), cpusetGet
Properties(3x), cpuset(4).
Man(1) output converted with
man2html