Make Sphinx handle better jobserver class documentation
Showing the changes to tools/lib/python (1 of 1 file). Show all
Unified · Split
| @@ -11,20 +11,23 @@ Interacts with the POSIX jobserver during the Kernel build time. · 10 unmodified lines | ||
| 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 |
| @@ -40,13 +43,14 @@ class JobserverExec: · 9 unmodified lines | ||
| 40 | 43 | Claim all slots from make using POSIX Jobserver. |
| 41 | 44 | |
| 42 | 45 | The main methods here are: |
| 46 | + | |
| 43 | 47 | - open(): reserves all slots; |
| 44 | 48 | - close(): method returns all used slots back to make; |
| 45 | − - run(): executes a command setting PARALLELISM=<available slots jobs + 1> | |
| 49 | + - run(): executes a command setting PARALLELISM=<available slots jobs + 1>. | |
| 46 | 50 | """ |
| 47 | 51 | |
| 48 | 52 | def __init__(self): |
| 49 | − """Initialize internal vars""" | |
| 53 | + """Initialize internal vars.""" | |
| 50 | 54 | self.claim = 0 |
| 51 | 55 | self.jobs = b"" |
| 52 | 56 | self.reader = None |
| @@ -54,7 +58,7 @@ class JobserverExec: · 1 unmodified line | ||
| 54 | 58 | self.is_open = False |
| 55 | 59 | |
| 56 | 60 | def open(self): |
| 57 | − """Reserve all available slots to be claimed later on""" | |
| 61 | + """Reserve all available slots to be claimed later on.""" | |
| 58 | 62 | |
| 59 | 63 | if self.is_open: |
| 60 | 64 | return |
| @@ -118,7 +122,7 @@ class JobserverExec: · 57 unmodified lines | ||
| 118 | 122 | self.is_open = True |
| 119 | 123 | |
| 120 | 124 | def close(self): |
| 121 | − """Return all reserved slots to Jobserver""" | |
| 125 | + """Return all reserved slots to Jobserver.""" | |
| 122 | 126 | |
| 123 | 127 | if not self.is_open: |
| 124 | 128 | return |