doc: cgroup: use graphviz code instead of ASCII art
Subsystems (2)
PATCH 1/2 doc: cgroup: use graphviz code instead of ASCII art
The graphviz looks better. This patch also fixes multiple build warnings:
"WARNING: Block quote ends without a blank line; unexpected unindent."
--- Documentation/admin-guide/cgroup-v2.rst | 83 ++++++++++++++++++++----- 1 file changed, 66 insertions(+), 17 deletions(-)
Documentation/admin-guide/cgroup-v2.rst +66 -17
@@ -344,10 +344,21 @@ example, to start a clean-up operation after all processes of a given sub-hierarchy have exited. The populated state updates and notifications are recursive. Consider the following sub-hierarchy where the numbers in the parentheses represent the numbers of processes -in each cgroup:: +in each cgroup: - A(4) - B(0) - C(1) - \ D(0) +.. kernel-render:: DOT + :alt: hierarchy + + digraph subhierarchy { + edge [ + arrowhead="none" + ]; + rankdir=LR; + + "A(4)" -> "B(0)"; + "B(0)" -> "C(1)"; + "B(0)" -> "D(0)"; + } A, B and C's "populated" fields would be 1 while D's 0. After the one process in C exits, B and C's "populated" fields would flip to "0" and
@@ -380,10 +391,21 @@ are specified, the last one is effective. Enabling a controller in a cgroup indicates that the distribution of the target resource across its immediate children will be controlled. Consider the following sub-hierarchy. The enabled controllers are -listed in parentheses:: +listed in parentheses: + +.. kernel-render:: DOT + :alt: hierarchy - A(cpu,memory) - B(memory) - C() - \ D() + digraph subhierarchy { + edge [ + arrowhead="none" + ]; + rankdir=LR; + + "A(cpu,memory)" -> "B(memory)"; + "B(memory)" -> "C()"; + "B(memory)" -> "D()"; + } As A has "cpu" and "memory" enabled, A will control the distribution of CPU cycles and memory to its children, in this case, B. As B has
@@ -497,12 +519,30 @@ in from or push out to outside the sub-hierarchy. For an example, let's assume cgroups C0 and C1 have been delegated to user U0 who created C00, C01 under C0 and C10 under C1 as follows and -all processes under C0 and C1 belong to U0:: +all processes under C0 and C1 belong to U0: + +.. kernel-render:: DOT + :alt: cgroup hierarchy - ~~~~~~~~~~~~~ - C0 - C00 - ~ cgroup ~ \ C01 - ~ hierarchy ~ - ~~~~~~~~~~~~~ - C1 - C10 + digraph hierarchyc0 { + edge [ + arrowhead="none" + ]; + + "C0" -> "C00"; + "C0" -> "C01"; + } + +.. kernel-render:: DOT + :alt: cgroup hierarchy + + digraph hierarchyc1 { + edge [ + arrowhead="none" + ]; + + "C1" -> "C10"; + } Let's also say U0 wants to write the PID of a process which is currently in C10 into "C00/cgroup.procs". U0 has write access to the
@@ -1505,12 +1545,21 @@ The limits are only applied at the peer level in the hierarchy. This means that in the diagram below, only groups A, B, and C will influence each other, and groups D and F will influence each other. Group G will influence nobody. - [root] - / | \ - A B C - / \ | - D F G - +.. kernel-render:: DOT + :alt: Peer hierarchy + + digraph hierarchy { + edge [ + arrowhead="none" + ]; + + "[root]" -> "A"; + "[root]" -> "B"; + "[root]" -> "C"; + "A" -> "D"; + "A" -> "F"; + "B" -> "G"; + } So the ideal way to configure this is to set io.latency in groups A, B, and C. Generally you do not want to set a value lower than the latency your device
Signature · 1 line
2.17.2
Jonathan Corbet
maintainerQuoted 4 lines · On Sun, 30 Dec 2018 17:49:45 +0100 Otto Sabart <[email protected]> wrote:
The graphviz looks better. This patch also fixes multiple build warnings:
"WARNING: Block quote ends without a blank line; unexpected unindent."Signed-off-by Otto Sabart <[email protected]>
The graphviz looks better *in some settings*, such as the formatted version of the docs. Please remember, though, that we need to preserve the readability of the plain-text documents as well, and my own feeling is that this patch is a step backward in that regard. I'll defer to Tejun on this if he feels otherwise, but my sense is that this is not something we want to do.
OTOH fixing the warnings would be a good thing; I think it just needs a bit more use of literal blocks. I would gladly accept a patch that did just that.
Thanks,
jon
Quoted 15 lines · Jonathan Corbet
Quoted 4 lines · On Sun, 30 Dec 2018 17:49:45 +0100 Otto Sabart <[email protected]> wrote:
The graphviz looks better. This patch also fixes multiple build warnings:
"WARNING: Block quote ends without a blank line; unexpected unindent."Signed-off-by Otto Sabart <[email protected]>The graphviz looks better *in some settings*, such as the formatted version of the docs. Please remember, though, that we need to preserve the readability of the plain-text documents as well, and my own feeling is that this patch is a step backward in that regard. I'll defer to Tejun on this if he feels otherwise, but my sense is that this is not something we want to do.
Quoted 3 lines
OTOH fixing the warnings would be a good thing; I think it just needs a bit more use of literal blocks. I would gladly accept a patch that did just that.
Ok, no problem. I will send another patch which fixes only these warnings.
Thanks,
Ota
Tejun Heo
maintainerQuoted 6 lines · Jonathan Corbet
Quoted 3 lines · On Sun, 30 Dec 2018 17:49:45 +0100 Otto Sabart <[email protected]> wrote:
The graphviz looks better. This patch also fixes multiple build warnings:
"WARNING: Block quote ends without a blank line; unexpected unindent."
Quoted 8 lines
Quoted 1 line
Signed-off-by Otto Sabart <[email protected]>The graphviz looks better *in some settings*, such as the formatted version of the docs. Please remember, though, that we need to preserve the readability of the plain-text documents as well, and my own feeling is that this patch is a step backward in that regard. I'll defer to Tejun on this if he feels otherwise, but my sense is that this is not something we want to do.
Yeah, I'd much prefer to prioritize source file readability. My anecdotal experience is that most folks read the text file directly.
Thanks.
Signature · 1 line
tejun