NAME¶
cpuset, cpuset_version, cpuset_pin, cpuset_size, cpuset_where, cpuset_unpin,
cpuset_alloc, cpuset_free, cpuset_cpus_nbits, cpuset_mems_nbits,
cpuset_setcpus, cpuset_setmems, cpuset_set_iopt, cpuset_set_sopt,
cpuset_getcpus, cpuset_getmems, cpuset_cpus_weight, cpuset_mems_weight,
cpuset_get_iopt, cpuset_get_sopt, cpuset_localcpus, cpuset_localmems,
cpuset_cpumemdist, cpuset_cpu2node, cpuset_addr2node, cpuset_create,
cpuset_delete, cpuset_query, cpuset_modify, cpuset_getcpusetpath,
cpuset_cpusetofpid, cpuset_mountpoint, cpuset_collides_exclusive, cpuset_nuke,
cpuset_init_pidlist, cpuset_pidlist_length, cpuset_get_pidlist,
cpuset_freepidlist, cpuset_move, cpuset_move_all, cpuset_move_cpuset_tasks,
cpuset_migrate, cpuset_migrate_all, cpuset_reattach,
cpuset_open_memory_pressure, cpuset_read_memory_pressure,
cpuset_close_memory_pressure, cpuset_c_rel_to_sys_cpu,
cpuset_c_sys_to_rel_cpu, cpuset_c_rel_to_sys_mem, cpuset_c_sys_to_rel_mem,
cpuset_p_rel_to_sys_cpu, cpuset_p_sys_to_rel_cpu, cpuset_p_rel_to_sys_mem,
cpuset_p_sys_to_rel_mem, cpuset_get_placement, cpuset_equal_placement,
cpuset_free_placement, cpuset_fts_open, cpuset_fts_read, cpuset_fts_reverse,
cpuset_fts_rewind, cpuset_fts_get_path, cpuset_fts_get_stat,
cpuset_fts_get_cpuset, cpuset_fts_get_errno, cpuset_fts_get_info,
cpuset_fts_close, cpuset_cpubind, cpuset_latestcpu, cpuset_membind,
cpuset_get_cpu_affinity, cpuset_set_cpu_affinity, cpuset_get_mem_affinity,
cpuset_export, cpuset_import, cpuset_function
- Library for managing CPU and Memory placement.
SYNOPSIS¶
#include <bitmask.h>
#include <cpuset.h>
cc ... -lcpuset
Basic cpuset routines¶
int cpuset_pin(int relcpu);
int cpuset_size();
int cpuset_where();
int cpuset_unpin();
Basic cpuset routines (Fortran interface)¶
include 'cpusetf.h'
integer relcpu
irtn = cpuset_pin(relcpu)
irtn = cpuset_size()
irtn = cpuset_unpin()
irtn = cpuset_where()
Cpuset library version.¶
int cpuset_version();
Allocate and free `struct cpuset *`:¶
struct cpuset *cpuset_alloc();
void cpuset_free(struct cpuset *cp);
Lengths of CPUs and Memory Nodes bitmasks - use to alloc
them:¶
int cpuset_cpus_nbits();
int cpuset_mems_nbits();
Set various attributes of a cpuset:¶
int cpuset_setcpus(struct cpuset *cp, const struct bitmask *cpus);
void cpuset_setmems(struct cpuset *cp, const struct bitmask *mems);
int cpuset_set_iopt(struct cpuset *cp, const char *optname, int val);
int cpuset_set_sopt(struct cpuset *cp, const char *optname, const char *val);
Query various attributes of a cpuset:¶
int cpuset_getcpus(const struct cpuset *cp, struct bitmask *cpus);
int cpuset_getmems(const struct cpuset *cp, struct bitmask *mems);
int cpuset_cpus_weight(const struct cpuset *cp);
int cpuset_mems_weight(const struct cpuset *cp);
int cpuset_get_iopt(const struct cpuset *cp, const char *optname);
const char *cpuset_get_sopt(const struct cpuset *cp, const char *optname);
Local CPUs and Memory Nodes:¶
int cpuset_localcpus(const struct bitmask *mems, struct bitmask *cpus);
int cpuset_localmems(const struct bitmask *cpus, struct bitmask *mems);
unsigned int cpuset_cpumemdist(int cpu, int mem);
int cpuset_cpu2node(int cpu);
int cpuset_addr2node(void *addr);
Create, delete, query, modify, list and examine cpusets:¶
int cpuset_create(const char *path, const struct *cp);
int cpuset_delete(const char *path);
int cpuset_query(struct cpuset *cp, const char *path);
int cpuset_modify(const char *path, const struct *cp);
char *cpuset_getcpusetpath(pid_t pid, char *buf, size_t size);
int cpuset_cpusetofpid(struct cpuset *cp, int pid);
const char *cpuset_mountpoint();
int cpuset_collides_exclusive(const char *cpusetpath, const struct cpuset *cp);
int cpuset_nuke(const char *path, unsigned int seconds);
List tasks (pids) currently attached to a cpuset:¶
struct cpuset_pidlist *cpuset_init_pidlist(const char *path, int recurse);
int cpuset_pidlist_length(const struct cpuset_pidlist *pl);
pid_t cpuset_get_pidlist(const struct cpuset_pidlist *pl, int i);
void cpuset_freepidlist(struct cpuset_pidlist *pl);
Attach tasks to cpusets:¶
int cpuset_move(pid_t p, const char *path);
int cpuset_move_all(struct cpuset_pid_list *pl, const char *path);
int cpuset_move_cpuset_tasks(const char *fromrelpath, const char *torelpath);
int cpuset_migrate(pid_t pid, const char *path);
int cpuset_migrate_all(struct cpuset_pid_list *pl, const char *path);
int cpuset_reattach(const char *path);
Monitor memory pressure caused by tasks in a cpuset:¶
int cpuset_open_memory_pressure(const char *cpusetpath);
int cpuset_read_memory_pressure(int han);
void cpuset_close_memory_pressure(int han);
Converting relative and system CPU and Memory Node numbers:¶
int cpuset_c_rel_to_sys_cpu(const struct cpuset *cp, int relcpu);
int cpuset_c_sys_to_rel_cpu(const struct cpuset *cp, int cpu);
int cpuset_c_rel_to_sys_mem(const struct cpuset *cp, int relmem);
int cpuset_c_sys_to_rel_mem(const struct cpuset *cp, int mem);
int cpuset_p_rel_to_sys_cpu(pid_t pid, int relcpu);
int cpuset_p_sys_to_rel_cpu(pid_t pid, int cpu);
int cpuset_p_rel_to_sys_mem(pid_t pid, int relmem);
int cpuset_p_sys_to_rel_mem(pid_t pid, int mem);
Placement operations for detecting cpuset migration:¶
struct cpuset_placement *cpuset_get_placement(pid_t pid);
int cpuset_equal_placement(const struct cpuset_placement *plc1,
const struct cpuset_placement *plc2);
void cpuset_free_placement(struct cpuset_placement *plc);
Traverse a cpuset hierarchy:¶
struct cpuset_fts_tree *cpuset_fts_open(const char *cpusetpath);
const struct cpuset_fts_entry *cpuset_fts_read(
struct cpuset_fts_tree *cs_tree);
void cpuset_fts_reverse(struct cpuset_fts_tree *cs_tree);
void cpuset_fts_rewind(struct cpuset_fts_tree *cs_tree);
const char *cpuset_fts_get_path(
const struct cpuset_fts_entry *cs_entry);
const struct stat *cpuset_fts_get_stat(
const struct cpuset_fts_entry *cs_entry);
const struct cpuset *cpuset_fts_get_cpuset(
const struct cpuset_fts_entry *cs_entry);
int cpuset_fts_get_errno(
const struct cpuset_fts_entry *cs_entry);
int cpuset_fts_get_info(
const struct cpuset_fts_entry *cs_entry);
void cpuset_fts_close(struct cpuset_fts_tree *cs_tree);
Bind to a CPU or Memory Node within the current cpuset:¶
int cpuset_cpubind(int cpu);
int cpuset_latestcpu(pid_t pid);
int cpuset_membind(int mem);
Export settings to and import from Text Representation:¶
int cpuset_export(const struct cpuset *cp, char *buf, int buflen);
int cpuset_import(struct cpuset *cp, const char *file,
int *errlinenum_ptr, char *errmsg_bufptr, int errmsg_buflen);
Calling [optional] cpuset_* API routines:¶
cpuset_function(const char *function_name);
DESCRIPTION¶
Cpusets are named subsets of a systems CPUs and Memory Nodes. On large SMP and
NUMA systems, it is commonly necessary to control which processes and threads
can run on which CPUs and Memory Nodes. Such placement can be used to improve
overall system performance, and to manage system utilization in accordance
with appropriate policies.
This cpuset library provides the mechanisms needed to create, destroy and manage
cpusets, and to control the placement of processes and threads within cpusets.
Though this library has many functions, most applications using it will only
need the few functions in the
Basic Cpuset API. These basic functions
enable an application to manage CPU and Memory placement on SMP and NUMA
systems within existing cpusets.
The
Advanced Cpuset API provides support for creating, destroying and
managing cpusets, and for more complex placement within cpusets. Workload
managers, batch processors and other system services can use the
Advanced
Cpuset API in order to manage cpusets across an entire system, or a
dedicated portion of a system.
All functions are part of the same library, and fully interoperable. A system
imposed permission model ensures that one application will not be able to make
changes to the cpusets or placement of other applications, outside of its
currently allowed cpuset.
Basic Cpuset API¶
The
Basic Cpuset API provides functions usable from
C for
processor and memory placement within a cpuset.
The basic functions enable an application to place various threads of its
execution on specific CPUs within its current cpuset, and perform related
functions such as asking how large the current cpuset is, and on which CPU
within the current cpuset a thread is currently executing.
The basic
cpuset_pin(int relcpu) function uses cpuset
relative numbering. In a cpuset of
N CPUs,
relcpu ranges from
zero to
N-
1. All functions in the
Advanced Cpuset
API use system wide CPU and Memory Node numbering, to provide a consistent
numbering regardless of cpuset configuration.
Memory placement is done automatically by the basic functions, local to the
requested CPU. Threads may only be pinned on a single CPU, or unpinned and
allowed the run of the entire current cpuset. This avoids the need to allocate
and free the bitmasks required to specify a set of several CPUs. The basic
functions do not support creating or removing cpusets, only the placement of
threads within an existing cpuset. This avoids the need to explicitly allocate
and free cpuset structures. Operations only apply to the current thread,
avoiding the need to pass the process id of the thread to be affected.
Basic Functions¶
The
Basic Cpuset API supports the following functions.
- int cpuset_pin(int relcpu);
- Pin the current task to execute only on the CPU
relcpu, which is a relative CPU number within the current cpuset of
that task. Also automatically pin the memory allowed to be used by the
current task to the memory on that same node (as determined by the
advanced cpuset_cpu2node() function).
- int cpuset_size();
- Return the number of CPUs in the current tasks cpuset. The
relative CPU numbers that are passed to the cpuset_pin() function
and that are returned by the cpuset_where() function, must be
between 0 and N - 1 inclusive, where N is the value
returned by cpuset_size().
- int cpuset_where();
- Return the CPU number, relative to the current tasks
cpuset, of the CPU on which the current task most recently executed. If a
task is allowed to execute on more than one CPU, then there is no
guarantee that the task is still executing on the CPU returned by
cpuset_where, by the time that the user code obtains the return value.
- int cpuset_unpin();
- Remove the CPU and Memory pinning affects of any previous
cpuset_pin call, allowing the current task to execute on any CPU in its
current cpuset and to allocate memory on any Memory Node in its current
cpuset.
ERRORS¶
- ENOSYS
- Invoked on an operating system kernel that does not support
cpusets.
- ENODEV
- Invoked on a system that supports cpusets, but when the
cpuset file system is not currently mounted at /dev/cpuset.
- ENOMEM
- Insufficient memory is available.
- EBUSY
- Attempted cpuset_delete() on a cpuset with attached
tasks.
- EBUSY
- Attempted cpuset_delete() on a cpuset with child
cpusets.
- ENOENT
- Attempted cpuset_create() in a parent cpuset that
doesn't exist.
- EEXIST
- Attempted cpuset_create() for a cpuset that already
exists.
- EEXIST
- Attempted to rename() a cpuset to a name that
already exists
- ENOTDIR
- Attempted to rename() a non-existant cpuset.
- E2BIG
- Attempted a write(2) system call on a special cpuset
file with a length larger than some kernel determined upper limit on the
length of such writes.
- ESRCH
- Attempted to cpuset_move() a non-existance
task.
- EACCES
- Attempted to cpuset_move() a task which one lacks
permission to move.
- EACCES
- Attempted to write(2) a memory_pressure
file.
- ENOSPC
- Attempted to cpuset_move() a task to an empty
cpuset.
- EINVAL
- The relcpu argument to cpuset_pin() is out of
range (not between zero and cpuset_size() - 1).
- EINVAL
- Attempted to change a cpuset in a way that would violate a
cpu_exclusive or mem_exclusive attribute of that cpuset or any of its
siblings.
- EINVAL
- Attempted to write an empty cpus or mems bitmask to the
kernel. The kernel creates new cpusets (via mkdir) with empty
cpus and mems, and the user level cpuset and bitmask code
works with empty masks. But the kernel will not allow an empty bitmask (no
bits set) to be written to the special cpus and mems files
of a cpuset.
- EIO
- Attempted to write(2) a string to a cpuset tasks
file that does not begin with an ASCII decimal integer.
- EIO
- Attempted to rename(2) a cpuset outside of its
current directory.
- ENOSPC
- Attempted to write(2) a list to a cpus file that did
not include any online cpus.
- ENOSPC
- Attempted to write(2) a list to a mems file
that did not include any online memory nodes.
- EACCES
- Attempted to add a cpu or mem to a cpuset that is not
already in its parent.
- EACCES
- Attempted to set cpu_exclusive or mem_exclusive on a cpuset
whose parent lacks the same setting.
- ENODEV
- The cpuset was removed by another task at the same time as
a write(2) was attempted on one of the special files in the cpuset
directory.
- EBUSY
- Attempted to remove a cpu or mem from a cpuset that is also
in a child of that cpuset.
- EFAULT
- Attempted to read or write a cpuset file using a buffer
that was outside your accessible address space.
- ENAMETOOLONG
- Attempted to read a /proc/pid/cpuset
file for a cpuset path that was longer than the kernel page size.
- ENAMETOOLONG
- Attempted to create a cpuset whose base directory name was
longer than 255 characters.
- ENAMETOOLONG
- Attempted to create a cpuset whose full pathname including
"/dev/cpuset" was longer than 4095 characters.
- ENXIO
- Attempted to create a cpu_exclusive cpuset whose
cpus covered just part of one or more physical processor packages,
such as including just one of the two Cores on a package. For Linux kernel
version 2.6.16 on i386 and x86_64, this operation is rejected with this
error to avoid a fatal kernel bug. Otherwise, this is a normal and
supported operation.
- EINVAL
- Specified a cpus or mems list to the kernel
which included a range with the second number smaller than the first
number.
- EINVAL
- Specified a cpus or mems list to the kernel
which included an invalid character in the string.
- ERANGE
- Specified a cpus or mems list to the kernel
which included a number too large for the kernel to set in its
bitmasks.
- ETIME
- Time limit for cpuset_nuke() operation reached
without successful completion of operation.
- ENOTEMPTY
- Tasks remain after multiple attempts by
cpuset_move_cpuset_tasks() to move them to a different cpuset.
- EPERM
- Lacked permission to kill (send a signal to) a
task.
- EPERM
- Lacked permission to read a cpuset or its
files.
- EPERM
- Attempted to unlink a per-cpuset file. Such files
can not be unlinked. They can only be removed by removing (rmdir)
the directory representing the cpuset that contains these files.
Advanced Cpuset API¶
For additional documentation on cpusets, and for details of the all the other,
advanced, routines, see /usr/share/doc/packages/libcpuset/libcpuset.html and
/usr/share/doc/packages/libbitmask/libbitmask.html. These same documents are
available in plain text format as
/usr/share/doc/packages/libcpuset/libcpuset.txt and
/usr/share/doc/packages/libbitmask/libbitmask.txt.
SEE ALSO¶
libbitmask(3)
AUTHOR¶
pj@sgi.com (Paul Jackson)