Skip to contentSkip to conversation

doc: cgroup: use graphviz code instead of ASCII art

PATCH In review Otto Sabart 3 participants 4 messages Dec 30, 2018 – Jan 2, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
index 7bf3f129c68b..80c88a0869e4 100644
@@ -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
maintainer
#1 lore raw
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."

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

#2 lore raw
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."

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

maintainer
#3 lore raw
In reply to Jonathan Corbet
Quoted 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

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