Documentation/cgroups/cgroups.txt

2 				-------
9 Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
38 ----------------------
52 schedules a resource or applies per-cgroup limits, but it may be
58 hierarchy, and a set of subsystems; each subsystem has system-specific
80 ----------------------------
97 different subsystems - having parallel hierarchies allows each
109 university server with various users - students, professors, system
141     # echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks
156        # echo pid > /sys/fs/cgroup/network/<new_class>/tasks
158        # echo pid > /sys/fs/cgroup/network/<orig_class>/tasks
167 ---------------------------------
171  - Each task in the system has a reference-counted pointer to a
174  - A css_set contains a set of reference-counted pointers to
181    and in performance-critical code, whereas operations that require a
185    css_set->tasks.
187  - A cgroup hierarchy filesystem can be mounted  for browsing and
190  - You can list all the tasks (by pid) attached to any cgroup.
195  - in init/main.c, to initialize the root cgroups and initial
198  - in fork and exit, to attach and detach a task from its css_set.
203 comma-separated list of subsystems to mount as the filesystem mount
210 hierarchy, the mount will fail with -EBUSY. Otherwise, a new hierarchy
216 error-recovery issues.
219 child cgroups created below the top-level cgroup, that hierarchy
223 No new system calls are added for cgroups - all support for
233  - tasks: list of tasks (by pid) attached to that cgroup.  This list
236  - cgroup.procs: list of tgids in the cgroup.  This list is not
241  - notify_on_release flag: run the release agent on exit?
242  - release_agent: the path to use for release notifications (this file
245 Other subsystems such as cpusets may add additional files in each
254 a large system into nested, dynamically changeable, "soft-partitions".
258 on a system into related sets of tasks.  A task may be re-attached to
263 css_set pointer - if there's an already existing css_set with the
275 each css_set that references the cgroup, and sub-iterating over
283 ------------------------------------
299 ---------------------------------
308 --------------------------
313  1) mount -t tmpfs cgroup_root /sys/fs/cgroup
314  2) mkdir /sys/fs/cgroup/cpuset
315  3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
317     the /sys/fs/cgroup virtual file system.
320     /sys/fs/cgroup/cpuset/tasks file for that cgroup.
327   mount -t tmpfs cgroup_root /sys/fs/cgroup
328   mkdir /sys/fs/cgroup/cpuset
329   mount -t cgroup cpuset -ocpuset /sys/fs/cgroup/cpuset
330   cd /sys/fs/cgroup/cpuset
333   /bin/echo 2-3 > cpuset.cpus
345 ---------------
351 # mount -t cgroup xxx /sys/fs/cgroup
363 /sys/fs/cgroup and create directories for each cgroup resource or resource
366 # mount -t tmpfs cgroup_root /sys/fs/cgroup
367 # mkdir /sys/fs/cgroup/rg1
371 # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1
375 # mount -o remount,cpuset,blkio hier1 /sys/fs/cgroup/rg1
379 Note this will add blkio to the hierarchy but won't remove memory or
381 # mount -o remount,blkio /sys/fs/cgroup/rg1
384 # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \
385   xxx /sys/fs/cgroup/rg1
394 Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the
395 tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1
399 # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent
403 If you want to create a new cgroup under /sys/fs/cgroup/rg1:
404 # cd /sys/fs/cgroup/rg1
426 has processes attached, or is held alive by other subsystem-specific
430 -----------------------
461 --------------------------------
465 mounting a pre-existing hierarchy, in order to refer to it by name
469 The name should match [\w.-]+
480 --------------------
486  - create a file descriptor for event notification using eventfd(2);
487  - open a control file to be monitored (e.g. memory.usage_in_bytes);
488  - write "<event_fd> <control_fd> <args>" to cgroup.event_control.
503 ------------
512 - subsys_id: a unique array index for the subsystem, indicating which
513   entry in cgroup->subsys[] this subsystem should be managing.
515 - name: should be initialized to a unique subsystem name. Should be
518 - early_init: indicate if the subsystem needs early initialization
526 -------------------
540 - while holding cgroup_mutex
541 - while holding the task's alloc_lock (via task_lock())
542 - inside an rcu_read_lock() section via rcu_dereference()
545 -----------------
549 - add an entry in linux/cgroup_subsys.h
550 - define a cgroup_subsys object called <name>_subsys
559 be successful no-ops.
570 larger subsystem-specific object), which will be initialized by the
584 cgroup->parent is still valid. (Note - can also be called for a
585 newly-created cgroup if an error occurs after this subsystem's
606   - it's guaranteed that all are from the same thread group
607   - @tset contains all tasks from the thread group whether or not
609   - the first task is the leader
623 A subsystem whose can_attach() has some side-effects should provide this
633 post-attachment activity that requires memory allocations or blocking.
663 (cgroup_mutex and ss->hierarchy_mutex held by caller)
667 the default hierarchy (which never has sub-cgroups) and a hierarchy
668 that is being created/destroyed (and hence has no sub-cgroups).