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. Note that the read side of the jobserver pipe is set to “blocking” mode.

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.