cpusetCreate - create a cpuset
SYNOPSIS
#include <cpuset.h>
int cpusetCreate(char *qname, cpuset_QueueDef_t *qdef);
DESCRIPTION
The cpusetCreate function is used to create a cpuset
queue. Only processes running root user ID are allowed to
create cpuset queues.
The qname argument is the name that will be assigned to
the new cpuset. The name of the cpuset must be a three to
eight character string. Queue names having one or two
characters are reserved for use by the system.
The qdef argument is a pointer to a cpuset_QueueDef_t
structure (defined in <cpuset.h>) that defines the
attributes of the queue to be created. The memory for the
cpuset_QueueDef_t is allocated using cpusetAlloc
QueueDef(3x) and it is released using cpusetFree
QueueDef(3x). The cpuset_QueueDef_t structure is defined
as follows:
typedef struct {
int flags;
char *permfile;
cpuset_CPUList_t *cpu;
} cpuset_QueueDef_t;
flags is used to specify various control options for the
cpuset queue. It is formed by OR-ing together zero or
more of the following values:
CCPPUUSSEETT_CCPPUU_EEXXCCLLUUSSIIVVEE
Defines a cpuset to be restricted. Only threads
attached to the cpuset queue (descendents of an
attached thread inherit the attachement) may exe
cute on the CPUs contained in the cpuset.
CCPPUUSSEETT_MMEEMMOORRYY_LLOOCCAALL
Threads assigned to the cpuset will attempt to
assign memory only from nodes within the cpuset.
Assignment of memory from outside the cpuset will
occur only if no free memory is available from
within the cpuset. No restrictions are made on
memory assignment to threads running outside the
cpuset.
CCPPUUSSEETT_MMEEMMOORRYY_EEXXCCLLUUSSIIVVEE
Threads assigned to the cpuset will attempt to
Assignment of memory from outside the cpuset will
occur only if no free memory is available from
within the cpuset. Threads not assigned to the
cpuset will not use memory from within the cpuset
unless no memory outside the cpuset is available.
If, at the time a cpuset is created, memory is
already assigned to threads that are already run
ning, no attempt will be made to explicitly move
this memory. If page migration is enabled, the
pages will be migrated when the system detects
that most references to the pages are non-local.
CCPPUUSSEETT_MMEEMMOORRYY_KKEERRNNEELL_AAVVOOIIDD
The kernel should attempt to avoid allocating mem
ory from nodes contained in this cpuset. If kernel
memory requests cannot be satisfied from outside
this cpuset, this option will be ignored and allo
cations will occur from within the cpuset. (This
avoidance currently extends only to keeping buffer
cache away from the protected nodes.)
CCPPUUSSEETT_MMEEMMOORRYY_MMAANNDDAATTOORRYY
The kernel will limit all memory allocations to
nodes that are contained in this cpuset. If memory
requests cannot be satisfied, the allocating pro
cess will sleep until memory is available. The
process will be killed if no more memory can be
allocated. See policies below.
CCPPUUSSEETT_PPOOLLIICCYY_PPAAGGEE
Requires MEMORY_MANDATORY. This is the default
policy if no policy is specified. This policy will
cause the kernel to page user pages to the swap
file (see swap(1M)) to free physical memory on the
nodes contained in this cpuset. If swap space is
exhausted, the process will be killed.
CCPPUUSSEETT_PPOOLLIICCYY_KKIILLLL
Requires MEMORY_MANDATORY. The kernel will attempt
to free as much space as possible from kernel
heaps, but will not page user pages to the swap
file. If all physical memory on the nodes con
tained in this cpuset are exhausted, the process
will be killed.
The permfile member is the name of the file that defines
the access permissions for the cpuset queue. The file
permissions of filename referenced by permfile define
access to the cpuset. Every time permissions need to be
checked, the current permissions of this file are used.
Thus, it is possible to change the access to a particular
cpuset without having to tear it down and recreate it,
simply by changing the access permissions. Read access to
cpuset, while execute permission allows the user to attach
a process to the cpuset.
The cpu member is a pointer to a cpuset_CPUList_t struc
ture. The memory for the cpuset_CPUList_t structure is
allocated and released when the cpuset_QueueDef_t struc
ture is allocated and released (see cpusetAlloc
QueueDef(3x)). The cpuset_CPUList_t structure contains
the list of CPUs assigned to the cpuset. The
cpuset_CPUList_t structure (defind in <cpuset.h>) is
defined as follows:
typedef struct {
int count;
int *list;
} cpuset_CPUList_t;
The count member defines the number of CPUs contained in
the list.
The list member is pointer to the list (an allocated
array) of the CPU IDs. The memory for the list array is
allocated and released when the cpuset_CPUList_t structure
is allocated and released.
EXAMPLES
This example creates a cpuset queue that has access con
troled by the file /usr/tmp/mypermfile, contains CPU IDs
4, 8, and 12, is CPU exclusive and memory exclusive:
cpuset_QueueDef_t *qdef;
char *qname = "myqueue";
/* 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_EXCLUSIVE;
qdef->permfile = "/usr/tmp/mypermfile"
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 */
if (!cpusetCreate(qname, qdef)) {
perror("cpusetCreate");
}
cpusetFreeQueueDef(qdef);
NOTES
cpusetCreate is found in the library "libcpuset.so", and
will be loaded if the option --llccppuusseett is used with cc(1)
or ld(1).
RESTRICTIONS
Not all of the above capabilities are implemented. See
the RESTRICTIONS secion in manual entry cpuset(4) for
details.
SEE ALSO
cpuset(1), cpusetAllocQueueDef(3x), cpusetFree
QueueDef(3x). cpuset(5).
DIAGNOSTICS
If successful, cpusetCreate returns a 1. If cpusetCreate
fails, it returns the value 0 and errno is set to indicate
the error. The possible values for errno include those
values set by fopen(3S) and the following:
ENODEV Request for CPU IDs that do not exist on the sys
tem.
EPERM Request for CPU 0 as part of an exclusive cpuset is
not permitted.
Man(1) output converted with
man2html