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