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 | A "normal" jobserver task, like the one initiated by a make subrocess would do: | 11 | A "normal" jobserver task, like the one initiated by a make subrocess would do: |
| 12 | 12 | ||
| 13 | - open read/write file descriptors to communicate with the job server; | 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 | claim = os.read(reader, 1) | 16 | claim = os.read(reader, 1) |
| 16 | - when the job finshes, call: | 17 | |
| 18 | - when the job finshes, call:: | ||
| 19 | |||
| 17 | os.write(writer, b"+") # os.write(writer, claim) | 20 | os.write(writer, b"+") # os.write(writer, claim) |
| 18 | 21 | ||
| 19 | Here, the goal is different: This script aims to get the remaining number | 22 | Here, the goal is different: This script aims to get the remaining number |
| 20 | of slots available, using all of them to run a command which handle tasks in | 23 | of slots available, using all of them to run a command which handle tasks in |
| 21 | parallel. To to that, it has a loop that ends only after there are no | 24 | parallel. To to that, it has a loop that ends only after there are no |
| 22 | slots left. It then increments the number by one, in order to allow a | 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 | $claim child to do the actual work. | 27 | $claim child to do the actual work. |
| 25 | 28 | ||
| 26 | The end goal here is to keep the total number of build tasks under the | 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 | See: | 32 | See: |
| 30 | https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver | 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 | Claim all slots from make using POSIX Jobserver. | 43 | Claim all slots from make using POSIX Jobserver. |
| 41 | 44 | ||
| 42 | The main methods here are: | 45 | The main methods here are: |
| 46 | |||
| 43 | - open(): reserves all slots; | 47 | - open(): reserves all slots; |
| 44 | - close(): method returns all used slots back to make; | 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 | def __init__(self): | 52 | def __init__(self): |
| 49 | """Initialize internal vars""" | 53 | """Initialize internal vars.""" |
| 50 | self.claim = 0 | 54 | self.claim = 0 |
| 51 | self.jobs = b"" | 55 | self.jobs = b"" |
| 52 | self.reader = None | 56 | self.reader = None |
| @@ -54,7 +58,7 @@ class JobserverExec: · 1 unmodified line | |||
| 54 | self.is_open = False | 58 | self.is_open = False |
| 55 | 59 | ||
| 56 | def open(self): | 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 | if self.is_open: | 63 | if self.is_open: |
| 60 | return | 64 | return |
| @@ -118,7 +122,7 @@ class JobserverExec: · 57 unmodified lines | |||
| 118 | self.is_open = True | 122 | self.is_open = True |
| 119 | 123 | ||
| 120 | def close(self): | 124 | def close(self): |
| 121 | """Return all reserved slots to Jobserver""" | 125 | """Return all reserved slots to Jobserver.""" |
| 122 | 126 | ||
| 123 | if not self.is_open: | 127 | if not self.is_open: |
| 124 | return | 128 | return |