Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: jobserver: do some documentation improvements
Make Sphinx handle better jobserver class documentation
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <18a9c1406bdead680e3ee5768c97ae8b2138e8ea.1768838938.git.mchehab+huawei@kernel.org>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
8b85f614
7a66b29d
+12
-8
+12
-8
tools/lib/python/jobserver.py
+12
-8
tools/lib/python/jobserver.py
···
11
11
A "normal" jobserver task, like the one initiated by a make subrocess would do:
12
12
13
13
- open read/write file descriptors to communicate with the job server;
14
-
- ask for one slot by calling:
14
+
- ask for one slot by calling::
15
+
15
16
claim = os.read(reader, 1)
16
-
- when the job finshes, call:
17
+
18
+
- when the job finshes, call::
19
+
17
20
os.write(writer, b"+") # os.write(writer, claim)
18
21
19
22
Here, the goal is different: This script aims to get the remaining number
20
23
of slots available, using all of them to run a command which handle tasks in
21
24
parallel. To to that, it has a loop that ends only after there are no
22
25
slots left. It then increments the number by one, in order to allow a
23
-
call equivalent to make -j$((claim+1)), e.g. having a parent make creating
26
+
call equivalent to ``make -j$((claim+1))``, e.g. having a parent make creating
24
27
$claim child to do the actual work.
25
28
26
29
The end goal here is to keep the total number of build tasks under the
27
-
limit established by the initial make -j$n_proc call.
30
+
limit established by the initial ``make -j$n_proc`` call.
28
31
29
32
See:
30
33
https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver
···
43
40
Claim all slots from make using POSIX Jobserver.
44
41
45
42
The main methods here are:
43
+
46
44
- open(): reserves all slots;
47
45
- close(): method returns all used slots back to make;
48
-
- run(): executes a command setting PARALLELISM=<available slots jobs + 1>
46
+
- run(): executes a command setting PARALLELISM=<available slots jobs + 1>.
49
47
"""
50
48
51
49
def __init__(self):
52
-
"""Initialize internal vars"""
50
+
"""Initialize internal vars."""
53
51
self.claim = 0
54
52
self.jobs = b""
55
53
self.reader = None
···
58
54
self.is_open = False
59
55
60
56
def open(self):
61
-
"""Reserve all available slots to be claimed later on"""
57
+
"""Reserve all available slots to be claimed later on."""
62
58
63
59
if self.is_open:
64
60
return
···
122
118
self.is_open = True
123
119
124
120
def close(self):
125
-
"""Return all reserved slots to Jobserver"""
121
+
"""Return all reserved slots to Jobserver."""
126
122
127
123
if not self.is_open:
128
124
return