The patch titled cgroup: fix and update documentation has been added to the -mm tree. Its filename is cgroup-fix-and-update-documentation.patch Before you just go and hit "reply", please: a) Consider who else should be cc'ed b) Prefer to cc a suitable mailing list as well c) Ideally: find the original patch on the mailing list and do a reply-to-all to that, adding suitable additional cc's *** Remember to use Documentation/SubmitChecklist when testing your code *** See http://www.zip.com.au/~akpm/linux/patches/stuff/added-to-mm.txt to find out what to do about this The current -mm tree may be found at http://userweb.kernel.org/~akpm/mmotm/ ------------------------------------------------------ Subject: cgroup: fix and update documentation From: Li Zefan <lizf@xxxxxxxxxxxxxx> Misc fixes and updates, make the doc consistent with current cgroup implementation. Signed-off-by: Li Zefan <lizf@xxxxxxxxxxxxxx> Acked-by: Paul Menage <menage@xxxxxxxxxx> Signed-off-by: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx> --- Documentation/cgroups.txt | 70 ++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 35 deletions(-) diff -puN Documentation/cgroups.txt~cgroup-fix-and-update-documentation Documentation/cgroups.txt --- a/Documentation/cgroups.txt~cgroup-fix-and-update-documentation +++ a/Documentation/cgroups.txt @@ -28,7 +28,7 @@ CONTENTS: 4. Questions 1. Control Groups -========== +================= 1.1 What are cgroups ? ---------------------- @@ -143,10 +143,10 @@ proliferation of such cgroups. Also lets say that the administrator would like to give enhanced network access temporarily to a student's browser (since it is night and the user -wants to do online gaming :) OR give one of the students simulation +wants to do online gaming :)) OR give one of the students simulation apps enhanced CPU power, -With ability to write pids directly to resource classes, its just a +With ability to write pids directly to resource classes, it's just a matter of : # echo pid > /mnt/network/<new_class>/tasks @@ -227,10 +227,13 @@ Each cgroup is represented by a director containing the following files describing that cgroup: - tasks: list of tasks (by pid) attached to that cgroup - - notify_on_release flag: run /sbin/cgroup_release_agent on exit? + - releasable flag: cgroup currently removeable? + - notify_on_release flag: run the release agent on exit? + - release_agent: the path to use for release notifications (this file + exists in the top cgroup only) Other subsystems such as cpusets may add additional files in each -cgroup dir +cgroup dir. New cgroups are created using the mkdir system call or shell command. The properties of a cgroup, such as its flags, are @@ -257,7 +260,7 @@ performance. To allow access from a cgroup to the css_sets (and hence tasks) that comprise it, a set of cg_cgroup_link objects form a lattice; each cg_cgroup_link is linked into a list of cg_cgroup_links for -a single cgroup on its cont_link_list field, and a list of +a single cgroup on its cgrp_link_list field, and a list of cg_cgroup_links for a single css_set on its cg_link_list. Thus the set of tasks in a cgroup can be listed by iterating over @@ -271,9 +274,6 @@ for cgroups, with a minimum of additiona 1.4 What does notify_on_release do ? ------------------------------------ -*** notify_on_release is disabled in the current patch set. It will be -*** reactivated in a future patch in a less-intrusive manner - If the notify_on_release flag is enabled (1) in a cgroup, then whenever the last task in the cgroup leaves (exits or attaches to some other cgroup) and the last child cgroup of that cgroup @@ -360,8 +360,8 @@ Now you want to do something with this c In this directory you can find several files: # ls -notify_on_release release_agent tasks -(plus whatever files are added by the attached subsystems) +notify_on_release releasable tasks +(plus whatever files added by the attached subsystems) Now attach your shell to this cgroup: # /bin/echo $$ > tasks @@ -404,19 +404,13 @@ with a subsystem id which will be assign Other fields in the cgroup_subsys object include: - subsys_id: a unique array index for the subsystem, indicating which - entry in cgroup->subsys[] this subsystem should be - managing. Initialized by cgroup_register_subsys(); prior to this - it should be initialized to -1 - -- hierarchy: an index indicating which hierarchy, if any, this - subsystem is currently attached to. If this is -1, then the - subsystem is not attached to any hierarchy, and all tasks should be - considered to be members of the subsystem's top_cgroup. It should - be initialized to -1. - -- name: should be initialized to a unique subsystem name prior to - calling cgroup_register_subsystem. Should be no longer than - MAX_CGROUP_TYPE_NAMELEN + entry in cgroup->subsys[] this subsystem should be managing. + +- name: should be initialized to a unique subsystem name. Should be + no longer than MAX_CGROUP_TYPE_NAMELEN. + +- early_init: indicate if the subsystem needs early initialization + at system boot. Each cgroup object created by the system has an array of pointers, indexed by subsystem id; this pointer is entirely managed by the @@ -434,8 +428,6 @@ situation. See kernel/cgroup.c for more details. Subsystems can take/release the cgroup_mutex via the functions -cgroup_lock()/cgroup_unlock(), and can -take/release the callback_mutex via the functions cgroup_lock()/cgroup_unlock(). 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 - inside an rcu_read_lock() section via rcu_dereference() 3.3 Subsystem API --------------------------- +----------------- Each subsystem should: @@ -455,7 +447,8 @@ Each subsystem may export the following methods are create/destroy. Any others that are null are presumed to be successful no-ops. -struct cgroup_subsys_state *create(struct cgroup *cont) +struct cgroup_subsys_state *create(struct cgroup_subsys *ss, + struct cgroup *cgrp) (cgroup_mutex held by caller) Called to create a subsystem state object for a cgroup. The @@ -470,7 +463,7 @@ identified by the passed cgroup object h it's the root of the hierarchy) and may be an appropriate place for initialization code. -void destroy(struct cgroup *cont) +void destroy(struct cgroup_subsys *ss, struct cgroup *cgrp) (cgroup_mutex held by caller) The cgroup system is about to destroy the passed cgroup; the subsystem @@ -481,7 +474,14 @@ cgroup->parent is still valid. (Note - c newly-created cgroup if an error occurs after this subsystem's create() method has been called for the new cgroup). -int can_attach(struct cgroup_subsys *ss, struct cgroup *cont, +void pre_destroy(struct cgroup_subsys *ss, struct cgroup *cgrp); +(cgroup_mutex held by caller) + +Called before checking the reference count on each subsystem. This may +be useful for subsystems which have some extra references even if +there are not tasks in the cgroup. + +int can_attach(struct cgroup_subsys *ss, struct cgroup *cgrp, struct task_struct *task) (cgroup_mutex held by caller) @@ -492,8 +492,8 @@ unspecified task can be moved into the c called on a fork. If this method returns 0 (success) then this should remain valid while the caller holds cgroup_mutex. -void attach(struct cgroup_subsys *ss, struct cgroup *cont, - struct cgroup *old_cont, struct task_struct *task) +void attach(struct cgroup_subsys *ss, struct cgroup *cgrp, + struct cgroup *old_cgrp, struct task_struct *task) Called after the task has been attached to the cgroup, to allow any post-attachment activity that requires memory allocations or blocking. @@ -505,9 +505,9 @@ registration for all existing tasks. void exit(struct cgroup_subsys *ss, struct task_struct *task) -Called during task exit +Called during task exit. -int populate(struct cgroup_subsys *ss, struct cgroup *cont) +int populate(struct cgroup_subsys *ss, struct cgroup *cgrp) Called after creation of a cgroup to allow a subsystem to populate the cgroup directory with file entries. The subsystem should make @@ -516,7 +516,7 @@ include/linux/cgroup.h for details). No method can return an error code, the error code is currently not always handled well. -void post_clone(struct cgroup_subsys *ss, struct cgroup *cont) +void post_clone(struct cgroup_subsys *ss, struct cgroup *cgrp) Called at the end of cgroup_clone() to do any paramater initialization which might be required before a task could attach. For _ Patches currently in -mm which might be from lizf@xxxxxxxxxxxxxx are cgroup-fix-and-update-documentation.patch cgroup-fix-comments.patch cgroup-clean-up-cgrouph.patch cgroup-fix-memory-leak-in-cgroup_get_sb.patch cgroup-fix-subsys-bitops.patch cgroup-remove-duplicate-code-in-find_css_set.patch cgroup-remove-dead-code-in-cgroup_get_rootdir.patch memcgroup-fix-and-update-documentation.patch memcgroup-remove-a-useless-vm_bug_on.patch memcgroup-return-negative-error-code-in-mem_cgroup_create.patch - To unsubscribe from this list: send the line "unsubscribe mm-commits" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html