diff options
author | Li Zefan <lizf@cn.fujitsu.com> | 2008-02-23 18:24:08 -0500 |
---|---|---|
committer | Linus Torvalds <torvalds@woody.linux-foundation.org> | 2008-02-23 20:13:24 -0500 |
commit | d19e0583300da82a6e27cd2116f558048502edaa (patch) | |
tree | 6c4d86cb9d5da8f752cd67be47a6d8940128034a /Documentation/cgroups.txt | |
parent | b5a0e011329431b90d315eaf6ca5fdb41df7a117 (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.txt | 66 |
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: | |||
28 | 4. Questions | 28 | 4. Questions |
29 | 29 | ||
30 | 1. Control Groups | 30 | 1. Control Groups |
31 | ========== | 31 | ================= |
32 | 32 | ||
33 | 1.1 What are cgroups ? | 33 | 1.1 What are cgroups ? |
34 | ---------------------- | 34 | ---------------------- |
@@ -143,10 +143,10 @@ proliferation of such cgroups. | |||
143 | 143 | ||
144 | Also lets say that the administrator would like to give enhanced network | 144 | Also lets say that the administrator would like to give enhanced network |
145 | access temporarily to a student's browser (since it is night and the user | 145 | access temporarily to a student's browser (since it is night and the user |
146 | wants to do online gaming :) OR give one of the students simulation | 146 | wants to do online gaming :)) OR give one of the students simulation |
147 | apps enhanced CPU power, | 147 | apps enhanced CPU power, |
148 | 148 | ||
149 | With ability to write pids directly to resource classes, its just a | 149 | With ability to write pids directly to resource classes, it's just a |
150 | matter of : | 150 | matter 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 | |||
227 | containing the following files describing that cgroup: | 227 | containing 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 | ||
232 | Other subsystems such as cpusets may add additional files in each | 235 | Other subsystems such as cpusets may add additional files in each |
233 | cgroup dir | 236 | cgroup dir. |
234 | 237 | ||
235 | New cgroups are created using the mkdir system call or shell | 238 | New cgroups are created using the mkdir system call or shell |
236 | command. The properties of a cgroup, such as its flags, are | 239 | command. The properties of a cgroup, such as its flags, are |
@@ -257,7 +260,7 @@ performance. | |||
257 | To allow access from a cgroup to the css_sets (and hence tasks) | 260 | To allow access from a cgroup to the css_sets (and hence tasks) |
258 | that comprise it, a set of cg_cgroup_link objects form a lattice; | 261 | that comprise it, a set of cg_cgroup_link objects form a lattice; |
259 | each cg_cgroup_link is linked into a list of cg_cgroup_links for | 262 | each cg_cgroup_link is linked into a list of cg_cgroup_links for |
260 | a single cgroup on its cont_link_list field, and a list of | 263 | a single cgroup on its cgrp_link_list field, and a list of |
261 | cg_cgroup_links for a single css_set on its cg_link_list. | 264 | cg_cgroup_links for a single css_set on its cg_link_list. |
262 | 265 | ||
263 | Thus the set of tasks in a cgroup can be listed by iterating over | 266 | Thus 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. | |||
271 | 1.4 What does notify_on_release do ? | 274 | 1.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 | |||
277 | If the notify_on_release flag is enabled (1) in a cgroup, then | 277 | If the notify_on_release flag is enabled (1) in a cgroup, then |
278 | whenever the last task in the cgroup leaves (exits or attaches to | 278 | whenever the last task in the cgroup leaves (exits or attaches to |
279 | some other cgroup) and the last child cgroup of that cgroup | 279 | some 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 | ||
361 | In this directory you can find several files: | 361 | In this directory you can find several files: |
362 | # ls | 362 | # ls |
363 | notify_on_release release_agent tasks | 363 | notify_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 | ||
366 | Now attach your shell to this cgroup: | 366 | Now 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. | |||
404 | Other fields in the cgroup_subsys object include: | 404 | Other 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 | ||
421 | Each cgroup object created by the system has an array of pointers, | 415 | Each cgroup object created by the system has an array of pointers, |
422 | indexed by subsystem id; this pointer is entirely managed by the | 416 | indexed by subsystem id; this pointer is entirely managed by the |
@@ -434,8 +428,6 @@ situation. | |||
434 | See kernel/cgroup.c for more details. | 428 | See kernel/cgroup.c for more details. |
435 | 429 | ||
436 | Subsystems can take/release the cgroup_mutex via the functions | 430 | Subsystems can take/release the cgroup_mutex via the functions |
437 | cgroup_lock()/cgroup_unlock(), and can | ||
438 | take/release the callback_mutex via the functions | ||
439 | cgroup_lock()/cgroup_unlock(). | 431 | cgroup_lock()/cgroup_unlock(). |
440 | 432 | ||
441 | Accessing a task's cgroup pointer may be done in the following ways: | 433 | Accessing 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 | ||
446 | 3.3 Subsystem API | 438 | 3.3 Subsystem API |
447 | -------------------------- | 439 | ----------------- |
448 | 440 | ||
449 | Each subsystem should: | 441 | Each subsystem should: |
450 | 442 | ||
@@ -455,7 +447,8 @@ Each subsystem may export the following methods. The only mandatory | |||
455 | methods are create/destroy. Any others that are null are presumed to | 447 | methods are create/destroy. Any others that are null are presumed to |
456 | be successful no-ops. | 448 | be successful no-ops. |
457 | 449 | ||
458 | struct cgroup_subsys_state *create(struct cgroup *cont) | 450 | struct 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 | ||
461 | Called to create a subsystem state object for a cgroup. The | 454 | Called 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 | |||
470 | it's the root of the hierarchy) and may be an appropriate place for | 463 | it's the root of the hierarchy) and may be an appropriate place for |
471 | initialization code. | 464 | initialization code. |
472 | 465 | ||
473 | void destroy(struct cgroup *cont) | 466 | void destroy(struct cgroup_subsys *ss, struct cgroup *cgrp) |
474 | (cgroup_mutex held by caller) | 467 | (cgroup_mutex held by caller) |
475 | 468 | ||
476 | The cgroup system is about to destroy the passed cgroup; the subsystem | 469 | The 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 | |||
481 | newly-created cgroup if an error occurs after this subsystem's | 474 | newly-created cgroup if an error occurs after this subsystem's |
482 | create() method has been called for the new cgroup). | 475 | create() method has been called for the new cgroup). |
483 | 476 | ||
484 | int can_attach(struct cgroup_subsys *ss, struct cgroup *cont, | 477 | void pre_destroy(struct cgroup_subsys *ss, struct cgroup *cgrp); |
478 | (cgroup_mutex held by caller) | ||
479 | |||
480 | Called before checking the reference count on each subsystem. This may | ||
481 | be useful for subsystems which have some extra references even if | ||
482 | there are not tasks in the cgroup. | ||
483 | |||
484 | int 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 | |||
492 | called on a fork. If this method returns 0 (success) then this should | 492 | called on a fork. If this method returns 0 (success) then this should |
493 | remain valid while the caller holds cgroup_mutex. | 493 | remain valid while the caller holds cgroup_mutex. |
494 | 494 | ||
495 | void attach(struct cgroup_subsys *ss, struct cgroup *cont, | 495 | void 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 | ||
498 | Called after the task has been attached to the cgroup, to allow any | 498 | Called after the task has been attached to the cgroup, to allow any |
499 | post-attachment activity that requires memory allocations or blocking. | 499 | post-attachment activity that requires memory allocations or blocking. |
@@ -505,9 +505,9 @@ registration for all existing tasks. | |||
505 | 505 | ||
506 | void exit(struct cgroup_subsys *ss, struct task_struct *task) | 506 | void exit(struct cgroup_subsys *ss, struct task_struct *task) |
507 | 507 | ||
508 | Called during task exit | 508 | Called during task exit. |
509 | 509 | ||
510 | int populate(struct cgroup_subsys *ss, struct cgroup *cont) | 510 | int populate(struct cgroup_subsys *ss, struct cgroup *cgrp) |
511 | 511 | ||
512 | Called after creation of a cgroup to allow a subsystem to populate | 512 | Called after creation of a cgroup to allow a subsystem to populate |
513 | the cgroup directory with file entries. The subsystem should make | 513 | the cgroup directory with file entries. The subsystem should make |
@@ -516,7 +516,7 @@ include/linux/cgroup.h for details). Note that although this | |||
516 | method can return an error code, the error code is currently not | 516 | method can return an error code, the error code is currently not |
517 | always handled well. | 517 | always handled well. |
518 | 518 | ||
519 | void post_clone(struct cgroup_subsys *ss, struct cgroup *cont) | 519 | void post_clone(struct cgroup_subsys *ss, struct cgroup *cgrp) |
520 | 520 | ||
521 | Called at the end of cgroup_clone() to do any paramater | 521 | Called at the end of cgroup_clone() to do any paramater |
522 | initialization which might be required before a task could attach. For | 522 | initialization which might be required before a task could attach. For |