xref: /linux/tools/lib/python/jobserver.py (revision 66c3bf974d48f8e5c5f94148e1171b62bd80e26d) 
1#!/usr/bin/env python3
2# SPDX-License-Identifier: GPL-2.0+
3#
4# pylint: disable=C0103,C0209
5#
6#
7
8"""
9Interacts with the POSIX jobserver during the Kernel build time.
10
11A "normal" jobserver task, like the one initiated by a make subrocess would do:
12
13    - open read/write file descriptors to communicate with the job server;
14    - ask for one slot by calling:
15        claim = os.read(reader, 1)
16    - when the job finshes, call:
17        os.write(writer, b"+")  # os.write(writer, claim)
18
19Here, the goal is different: This script aims to get the remaining number
20of slots available, using all of them to run a command which handle tasks in
21parallel. To to that, it has a loop that ends only after there are no
22slots left. It then increments the number by one, in order to allow a
23call equivalent to make -j$((claim+1)), e.g. having a parent make creating
24$claim child to do the actual work.
25
26The end goal here is to keep the total number of build tasks under the
27limit established by the initial make -j$n_proc call.
28
29See:
30    https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver
31"""
32
33import errno
34import os
35import subprocess
36import sys
37
38class JobserverExec:
39    """
40    Claim all slots from make using POSIX Jobserver.
41
42    The main methods here are:
43    - open(): reserves all slots;
44    - close(): method returns all used slots back to make;
45    - run(): executes a command setting PARALLELISM=<available slots jobs + 1>
46    """
47
48    def __init__(self):
49        """Initialize internal vars"""
50        self.claim = 0
51        self.jobs = b""
52        self.reader = None
53        self.writer = None
54        self.is_open = False
55
56    def open(self):
57        """Reserve all available slots to be claimed later on"""
58
59        if self.is_open:
60            return
61
62        try:
63            # Fetch the make environment options.
64            flags = os.environ["MAKEFLAGS"]
65            # Look for "--jobserver=R,W"
66            # Note that GNU Make has used --jobserver-fds and --jobserver-auth
67            # so this handles all of them.
68            opts = [x for x in flags.split(" ") if x.startswith("--jobserver")]
69
70            # Parse out R,W file descriptor numbers and set them nonblocking.
71            # If the MAKEFLAGS variable contains multiple instances of the
72            # --jobserver-auth= option, the last one is relevant.
73            fds = opts[-1].split("=", 1)[1]
74
75            # Starting with GNU Make 4.4, named pipes are used for reader
76            # and writer.
77            # Example argument: --jobserver-auth=fifo:/tmp/GMfifo8134
78            _, _, path = fds.partition("fifo:")
79
80            if path:
81                self.reader = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
82                self.writer = os.open(path, os.O_WRONLY)
83            else:
84                self.reader, self.writer = [int(x) for x in fds.split(",", 1)]
85                # Open a private copy of reader to avoid setting nonblocking
86                # on an unexpecting process with the same reader fd.
87                self.reader = os.open("/proc/self/fd/%d" % (self.reader),
88                                      os.O_RDONLY | os.O_NONBLOCK)
89
90            # Read out as many jobserver slots as possible
91            while True:
92                try:
93                    slot = os.read(self.reader, 8)
94                    if not slot:
95                        # Clear self.jobs to prevent us from probably writing incorrect file.
96                        self.jobs = b""
97                        raise ValueError("unexpected empty token from jobserver fd, invalid '--jobserver-auth=' setting?")
98                    self.jobs += slot
99                except (OSError, IOError) as e:
100                    if e.errno == errno.EWOULDBLOCK:
101                        # Stop at the end of the jobserver queue.
102                        break
103                    # If something went wrong, give back the jobs.
104                    if self.jobs:
105                        os.write(self.writer, self.jobs)
106                    raise e
107
108            # Add a bump for our caller's reserveration, since we're just going
109            # to sit here blocked on our child.
110            self.claim = len(self.jobs) + 1
111
112        except (KeyError, IndexError, ValueError, OSError, IOError) as e:
113            print(f"jobserver: warning: {repr(e)}", file=sys.stderr)
114            # Any missing environment strings or bad fds should result in just
115            # not being parallel.
116            self.claim = None
117
118        self.is_open = True
119
120    def close(self):
121        """Return all reserved slots to Jobserver"""
122
123        if not self.is_open:
124            return
125
126        # Return all the reserved slots.
127        if len(self.jobs):
128            os.write(self.writer, self.jobs)
129
130        self.is_open = False
131
132    def __enter__(self):
133        self.open()
134        return self
135
136    def __exit__(self, exc_type, exc_value, exc_traceback):
137        self.close()
138
139    def run(self, cmd, *args, **pwargs):
140        """
141        Run a command setting PARALLELISM env variable to the number of
142        available job slots (claim) + 1, e.g. it will reserve claim slots
143        to do the actual build work, plus one to monitor its children.
144        """
145        self.open()             # Ensure that self.claim is set
146
147        # We can only claim parallelism if there was a jobserver (i.e. a
148        # top-level "-jN" argument) and there were no other failures. Otherwise
149        # leave out the environment variable and let the child figure out what
150        # is best.
151        if self.claim:
152            os.environ["PARALLELISM"] = str(self.claim)
153
154        return subprocess.call(cmd, *args, **pwargs)
155