make: POSIX Jobserver
13.1.1 POSIX Jobserver Interaction
----------------------------------
On POSIX systems the jobserver is implemented as a simple UNIX pipe.
The pipe will be pre-loaded with one single-character token for each
available job. To obtain an extra slot you must read a single character
from the jobserver pipe; to release a slot you must write a single
character back into the jobserver pipe.
To access the pipe you must parse the 'MAKEFLAGS' variable and look
for the argument string '--jobserver-auth=R,W' where 'R' and 'W' are
non-negative integers representing file descriptors: 'R' is the read
file descriptor and 'W' is the write file descriptor.
It's important that when you release the job slot, you write back the
same character you read from the pipe for that slot. Don't assume that
all tokens are the same character; different characters may have
different meanings to GNU 'make'. The order is not important, since
'make' has no idea in what order jobs will complete anyway.
There are various error conditions you must consider to ensure your
implementation is robust:
* Usually you will have a command-line argument controlling the
parallel operation of your tool. Consider whether your tool should
detect situations where both the jobserver and the command-line
argument are specified, and how it should react.
* If your tool determines that the '--jobserver-auth' option is
available in 'MAKEFLAGS' but that the file descriptors specified
are closed, this means that the calling 'make' process did not
think that your tool was a recursive 'make' invocation (e.g., the
command line was not prefixed with a '+' character). You should
notify your users of this situation.
* Your tool should also examine the first word of the 'MAKEFLAGS'
variable and look for the character 'n'. If this character is
present then 'make' was invoked with the '-n' option and your tool
should stop without performing any operations.
* Your tool should be sure to write back the tokens it read, even
under error conditions. This includes not only errors in your tool
but also outside influences such as interrupts ('SIGINT'), etc.
You may want to install signal handlers to manage this write-back.
Info Catalog
make: Job Slots
make: Job Slots
make: Windows Jobserver