lkml.org 
[lkml]   [2014]   [Apr]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
Date
From
Subject[PATCH v4] control groups: documentation improvements
On 16/04/2014 22:00, Tejun Heo wrote:
> On Wed, Apr 02, 2014 at 02:17:13PM +0100, Glyn Normington wrote:
>> From: Glyn Normington<gnormington@gopivotal.com>
>>
>> Various clarifications to make the control groups documentation
>> easier to understand, especially for newcomers.
> Patch doesn't apply. Can you please re-generate the patch with 'diff
> -u' and send it as an attachment?
>
> Thanks.
From: Glyn Normington<gnormington@gopivotal.com>

Please see the attachment for the patch created using 'diff -u'. I
checked it applied ok with:

patch -p1 < ~/patchfile

at the latest HEAD (6ca2a88).

Related LKML thread:

http://lkml.iu.edu//hypermail/linux/kernel/1402.0/02419.html

Signed-off-by: Glyn Normington<gnormington@gopivotal.com>

diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt
index 821de56..f086b70 100644
--- a/Documentation/cgroups/cgroups.txt
+++ b/Documentation/cgroups/cgroups.txt
@@ -24,6 +24,7 @@ CONTENTS:
2.1 Basic Usage
2.2 Attaching processes
2.3 Mounting hierarchies by name
+ 2.4 Mounting hierarchies with no subsystems
3. Kernel API
3.1 Overview
3.2 Synchronization
@@ -43,24 +44,29 @@ specialized behaviour.

Definitions:

-A *cgroup* associates a set of tasks with a set of parameters for one
-or more subsystems.
+A *cgroup* associates a set of tasks with zero or more subsystems.

-A *subsystem* is a module that makes use of the task grouping
-facilities provided by cgroups to treat groups of tasks in
-particular ways. A subsystem is typically a "resource controller" that
+A *subsystem* is a module that treats the tasks of each cgroup in a
+particular way. A subsystem is typically a "resource controller" that
schedules a resource or applies per-cgroup limits, but it may be
-anything that wants to act on a group of processes, e.g. a
-virtualization subsystem.
+anything that wants to act on a group of tasks, e.g. a virtualization
+subsystem.

-A *hierarchy* is a set of cgroups arranged in a tree, such that
-every task in the system is in exactly one of the cgroups in the
-hierarchy, and a set of subsystems; each subsystem has system-specific
-state attached to each cgroup in the hierarchy. Each hierarchy has
-an instance of the cgroup virtual filesystem associated with it.
+A *hierarchy* is a non-empty set of cgroups arranged in a tree and a
+set of subsystems such that the cgroups in the hierarchy
+partition all the tasks in the system (in other words, every task in the
+system is in exactly one of the cgroups in the hierarchy) and each
+subsystem attaches its own state to each cgroup in the hierarchy.

-At any one time there may be multiple active hierarchies of task
-cgroups. Each hierarchy is a partition of all tasks in the system.
+There may be zero or more active hierarchies. Each hierarchy has an
+instance of the cgroup virtual filesystem associated with it. The tree
+of cgroups is represented by the directory tree in the cgroup virtual
+filesystem.
+
+The sets of subsystems participating in distinct hierarchies are either
+identical or disjoint. If the sets are identical, the virtual filesystems
+associated with the hierarchies have identical content and a change in
+one is automatically reflected in all the others.

User-level code may create and destroy cgroups by name in an
instance of the cgroup virtual file system, specify and query to
@@ -69,9 +75,9 @@ a cgroup. Those creations and assignments only affect the hierarchy
associated with that instance of the cgroup file system.

On their own, the only use for cgroups is for simple job
-tracking. The intention is that other subsystems hook into the generic
+tracking. The intention is that subsystems hook into the generic
cgroup support to provide new attributes for cgroups, such as
-accounting/limiting the resources which processes in a cgroup can
+accounting/limiting the resources which tasks in a cgroup can
access. For example, cpusets (see Documentation/cgroups/cpusets.txt) allow
you to associate a set of CPUs and a set of memory nodes with the
tasks in each cgroup.
@@ -79,12 +85,12 @@ tasks in each cgroup.
1.2 Why are cgroups needed ?
----------------------------

-There are multiple efforts to provide process aggregations in the
+There are multiple efforts to provide task aggregations in the
Linux kernel, mainly for resource-tracking purposes. Such efforts
include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server
namespaces. These all require the basic notion of a
-grouping/partitioning of processes, with newly forked processes ending
-up in the same group (cgroup) as their parent process.
+grouping/partitioning of tasks, with newly forked tasks ending
+up in the same group (cgroup) as their parent task.

The kernel cgroup patch provides the minimum essential kernel
mechanisms required to efficiently implement such groups. It has
@@ -418,11 +424,11 @@ To remove a cgroup, just use rmdir:
# rmdir my_sub_cs

This will fail if the cgroup is in use (has cgroups inside, or
-has processes attached, or is held alive by other subsystem-specific
+has tasks attached, or is held alive by other subsystem-specific
reference).

-2.2 Attaching processes
------------------------
+2.2 Attaching tasks
+-------------------

# /bin/echo PID > tasks

@@ -450,7 +456,7 @@ move it into a new cgroup (possibly the root cgroup) by writing to the
new cgroup's tasks file.

Note: Due to some restrictions enforced by some cgroup subsystems, moving
-a process to another cgroup can fail.
+a task to another cgroup can fail.

2.3 Mounting hierarchies by name
--------------------------------
@@ -471,6 +477,13 @@ you give a subsystem a name.
The name of the subsystem appears as part of the hierarchy description
in /proc/mounts and /proc/<pid>/cgroups.

+2.4 Mounting hierarchies with no subsystems
+-------------------------------------------
+
+To mount a hierarchy with no associated subsystems, specify a name
+for the hierarchy and the dummy subsystem name "none". For example:
+
+# mount -t cgroup -o name=hier0,none hier0 /sys/fs/cgroup/h0

3. Kernel API
=============
@@ -658,7 +671,7 @@ A: bash's builtin 'echo' command does not check calls to write() against
errors. If you use it in the cgroup file system, you won't be
able to tell whether a command succeeded or failed.

-Q: When I attach processes, only the first of the line gets really attached !
+Q: When I attach tasks, only the first of the line gets really attached !
A: We can only return one error code per call to write(). So you should also
put only ONE PID.
\
 
 \ /
  Last update: 2014-04-17 13:21    [W:0.270 / U:1.768 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site