aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/cgroups.txt
diff options
context:
space:
mode:
authorLi Zefan <lizf@cn.fujitsu.com>2008-02-23 18:24:08 -0500
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2008-02-23 20:13:24 -0500
commitd19e0583300da82a6e27cd2116f558048502edaa (patch)
tree6c4d86cb9d5da8f752cd67be47a6d8940128034a /Documentation/cgroups.txt
parentb5a0e011329431b90d315eaf6ca5fdb41df7a117 (diff)
cgroup: fix and update documentation
Misc fixes and updates, make the doc consistent with current cgroup implementation. Signed-off-by: Li Zefan <lizf@cn.fujitsu.com> Acked-by: Paul Menage <menage@google.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/cgroups.txt')
-rw-r--r--Documentation/cgroups.txt66
1 files changed, 33 insertions, 33 deletions
diff --git a/Documentation/cgroups.txt b/Documentation/cgroups.txt
index 42d7c4cb39cd..31d12e21ff8a 100644
--- a/Documentation/cgroups.txt
+++ b/Documentation/cgroups.txt
@@ -28,7 +28,7 @@ CONTENTS:
284. Questions 284. Questions
29 29
301. Control Groups 301. Control Groups
31========== 31=================
32 32
331.1 What are cgroups ? 331.1 What are cgroups ?
34---------------------- 34----------------------
@@ -143,10 +143,10 @@ proliferation of such cgroups.
143 143
144Also lets say that the administrator would like to give enhanced network 144Also lets say that the administrator would like to give enhanced network
145access temporarily to a student's browser (since it is night and the user 145access temporarily to a student's browser (since it is night and the user
146wants to do online gaming :) OR give one of the students simulation 146wants to do online gaming :)) OR give one of the students simulation
147apps enhanced CPU power, 147apps enhanced CPU power,
148 148
149With ability to write pids directly to resource classes, its just a 149With ability to write pids directly to resource classes, it's just a
150matter of : 150matter of :
151 151
152 # echo pid > /mnt/network/<new_class>/tasks 152 # echo pid > /mnt/network/<new_class>/tasks
@@ -227,10 +227,13 @@ Each cgroup is represented by a directory in the cgroup file system
227containing the following files describing that cgroup: 227containing the following files describing that cgroup:
228 228
229 - tasks: list of tasks (by pid) attached to that cgroup 229 - tasks: list of tasks (by pid) attached to that cgroup
230 - notify_on_release flag: run /sbin/cgroup_release_agent on exit? 230 - releasable flag: cgroup currently removeable?
231 - notify_on_release flag: run the release agent on exit?
232 - release_agent: the path to use for release notifications (this file
233 exists in the top cgroup only)
231 234
232Other subsystems such as cpusets may add additional files in each 235Other subsystems such as cpusets may add additional files in each
233cgroup dir 236cgroup dir.
234 237
235New cgroups are created using the mkdir system call or shell 238New cgroups are created using the mkdir system call or shell
236command. The properties of a cgroup, such as its flags, are 239command. The properties of a cgroup, such as its flags, are
@@ -257,7 +260,7 @@ performance.
257To allow access from a cgroup to the css_sets (and hence tasks) 260To allow access from a cgroup to the css_sets (and hence tasks)
258that comprise it, a set of cg_cgroup_link objects form a lattice; 261that comprise it, a set of cg_cgroup_link objects form a lattice;
259each cg_cgroup_link is linked into a list of cg_cgroup_links for 262each cg_cgroup_link is linked into a list of cg_cgroup_links for
260a single cgroup on its cont_link_list field, and a list of 263a single cgroup on its cgrp_link_list field, and a list of
261cg_cgroup_links for a single css_set on its cg_link_list. 264cg_cgroup_links for a single css_set on its cg_link_list.
262 265
263Thus the set of tasks in a cgroup can be listed by iterating over 266Thus the set of tasks in a cgroup can be listed by iterating over
@@ -271,9 +274,6 @@ for cgroups, with a minimum of additional kernel code.
2711.4 What does notify_on_release do ? 2741.4 What does notify_on_release do ?
272------------------------------------ 275------------------------------------
273 276
274*** notify_on_release is disabled in the current patch set. It will be
275*** reactivated in a future patch in a less-intrusive manner
276
277If the notify_on_release flag is enabled (1) in a cgroup, then 277If the notify_on_release flag is enabled (1) in a cgroup, then
278whenever the last task in the cgroup leaves (exits or attaches to 278whenever the last task in the cgroup leaves (exits or attaches to
279some other cgroup) and the last child cgroup of that cgroup 279some other cgroup) and the last child cgroup of that cgroup
@@ -360,8 +360,8 @@ Now you want to do something with this cgroup.
360 360
361In this directory you can find several files: 361In this directory you can find several files:
362# ls 362# ls
363notify_on_release release_agent tasks 363notify_on_release releasable tasks
364(plus whatever files are added by the attached subsystems) 364(plus whatever files added by the attached subsystems)
365 365
366Now attach your shell to this cgroup: 366Now attach your shell to this cgroup:
367# /bin/echo $$ > tasks 367# /bin/echo $$ > tasks
@@ -404,19 +404,13 @@ with a subsystem id which will be assigned by the cgroup system.
404Other fields in the cgroup_subsys object include: 404Other fields in the cgroup_subsys object include:
405 405
406- subsys_id: a unique array index for the subsystem, indicating which 406- subsys_id: a unique array index for the subsystem, indicating which
407 entry in cgroup->subsys[] this subsystem should be 407 entry in cgroup->subsys[] this subsystem should be managing.
408 managing. Initialized by cgroup_register_subsys(); prior to this
409 it should be initialized to -1
410 408
411- hierarchy: an index indicating which hierarchy, if any, this 409- name: should be initialized to a unique subsystem name. Should be
412 subsystem is currently attached to. If this is -1, then the 410 no longer than MAX_CGROUP_TYPE_NAMELEN.
413 subsystem is not attached to any hierarchy, and all tasks should be
414 considered to be members of the subsystem's top_cgroup. It should
415 be initialized to -1.
416 411
417- name: should be initialized to a unique subsystem name prior to 412- early_init: indicate if the subsystem needs early initialization
418 calling cgroup_register_subsystem. Should be no longer than 413 at system boot.
419 MAX_CGROUP_TYPE_NAMELEN
420 414
421Each cgroup object created by the system has an array of pointers, 415Each cgroup object created by the system has an array of pointers,
422indexed by subsystem id; this pointer is entirely managed by the 416indexed by subsystem id; this pointer is entirely managed by the
@@ -434,8 +428,6 @@ situation.
434See kernel/cgroup.c for more details. 428See kernel/cgroup.c for more details.
435 429
436Subsystems can take/release the cgroup_mutex via the functions 430Subsystems can take/release the cgroup_mutex via the functions
437cgroup_lock()/cgroup_unlock(), and can
438take/release the callback_mutex via the functions
439cgroup_lock()/cgroup_unlock(). 431cgroup_lock()/cgroup_unlock().
440 432
441Accessing a task's cgroup pointer may be done in the following ways: 433Accessing a task's cgroup pointer may be done in the following ways:
@@ -444,7 +436,7 @@ Accessing a task's cgroup pointer may be done in the following ways:
444- inside an rcu_read_lock() section via rcu_dereference() 436- inside an rcu_read_lock() section via rcu_dereference()
445 437
4463.3 Subsystem API 4383.3 Subsystem API
447-------------------------- 439-----------------
448 440
449Each subsystem should: 441Each subsystem should:
450 442
@@ -455,7 +447,8 @@ Each subsystem may export the following methods. The only mandatory
455methods are create/destroy. Any others that are null are presumed to 447methods are create/destroy. Any others that are null are presumed to
456be successful no-ops. 448be successful no-ops.
457 449
458struct cgroup_subsys_state *create(struct cgroup *cont) 450struct cgroup_subsys_state *create(struct cgroup_subsys *ss,
451 struct cgroup *cgrp)
459(cgroup_mutex held by caller) 452(cgroup_mutex held by caller)
460 453
461Called to create a subsystem state object for a cgroup. The 454Called to create a subsystem state object for a cgroup. The
@@ -470,7 +463,7 @@ identified by the passed cgroup object having a NULL parent (since
470it's the root of the hierarchy) and may be an appropriate place for 463it's the root of the hierarchy) and may be an appropriate place for
471initialization code. 464initialization code.
472 465
473void destroy(struct cgroup *cont) 466void destroy(struct cgroup_subsys *ss, struct cgroup *cgrp)
474(cgroup_mutex held by caller) 467(cgroup_mutex held by caller)
475 468
476The cgroup system is about to destroy the passed cgroup; the subsystem 469The cgroup system is about to destroy the passed cgroup; the subsystem
@@ -481,7 +474,14 @@ cgroup->parent is still valid. (Note - can also be called for a
481newly-created cgroup if an error occurs after this subsystem's 474newly-created cgroup if an error occurs after this subsystem's
482create() method has been called for the new cgroup). 475create() method has been called for the new cgroup).
483 476
484int can_attach(struct cgroup_subsys *ss, struct cgroup *cont, 477void pre_destroy(struct cgroup_subsys *ss, struct cgroup *cgrp);
478(cgroup_mutex held by caller)
479
480Called before checking the reference count on each subsystem. This may
481be useful for subsystems which have some extra references even if
482there are not tasks in the cgroup.
483
484int can_attach(struct cgroup_subsys *ss, struct cgroup *cgrp,
485 struct task_struct *task) 485 struct task_struct *task)
486(cgroup_mutex held by caller) 486(cgroup_mutex held by caller)
487 487
@@ -492,8 +492,8 @@ unspecified task can be moved into the cgroup. Note that this isn't
492called on a fork. If this method returns 0 (success) then this should 492called on a fork. If this method returns 0 (success) then this should
493remain valid while the caller holds cgroup_mutex. 493remain valid while the caller holds cgroup_mutex.
494 494
495void attach(struct cgroup_subsys *ss, struct cgroup *cont, 495void attach(struct cgroup_subsys *ss, struct cgroup *cgrp,
496 struct cgroup *old_cont, struct task_struct *task) 496 struct cgroup *old_cgrp, struct task_struct *task)
497 497
498Called after the task has been attached to the cgroup, to allow any 498Called after the task has been attached to the cgroup, to allow any
499post-attachment activity that requires memory allocations or blocking. 499post-attachment activity that requires memory allocations or blocking.
@@ -505,9 +505,9 @@ registration for all existing tasks.
505 505
506void exit(struct cgroup_subsys *ss, struct task_struct *task) 506void exit(struct cgroup_subsys *ss, struct task_struct *task)
507 507
508Called during task exit 508Called during task exit.
509 509
510int populate(struct cgroup_subsys *ss, struct cgroup *cont) 510int populate(struct cgroup_subsys *ss, struct cgroup *cgrp)
511 511
512Called after creation of a cgroup to allow a subsystem to populate 512Called after creation of a cgroup to allow a subsystem to populate
513the cgroup directory with file entries. The subsystem should make 513the cgroup directory with file entries. The subsystem should make
@@ -516,7 +516,7 @@ include/linux/cgroup.h for details). Note that although this
516method can return an error code, the error code is currently not 516method can return an error code, the error code is currently not
517always handled well. 517always handled well.
518 518
519void post_clone(struct cgroup_subsys *ss, struct cgroup *cont) 519void post_clone(struct cgroup_subsys *ss, struct cgroup *cgrp)
520 520
521Called at the end of cgroup_clone() to do any paramater 521Called at the end of cgroup_clone() to do any paramater
522initialization which might be required before a task could attach. For 522initialization which might be required before a task could attach. For