File: make.info,  Node: POSIX Jobserver,  Next: Windows Jobserver,  Prev: Job_Slots.php">Job Slots,  Up: Job_Slots.php">Job Slots

13.1.1 POSIX Jobserver Interaction
----------------------------------

On POSIX systems the jobserver is implemented in one of two ways: on
systems that support it, GNU 'make' will create a named pipe and use
that for the jobserver.  In this case the auth option will have the form
'--jobserver-auth=fifo:PATH' where 'PATH' is the pathname of the named
pipe.  To access the jobserver you should open the named pipe path and
read/write to it as described below.

   If the system doesn't support named pipes, or if the user provided
the '--jobserver-style' option and specified 'pipe', then the jobserver
will be implemented as a simple UNIX pipe.  In this case the auth option
will have the form '--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.  If either or both
of these file descriptors are negative, it means the jobserver is
disabled for this process.

   When using a simple pipe, only command lines that 'make' understands
to be recursive invocations of 'make' (*note How the 'MAKE' Variable
Works: MAKE Variable.) will have access to the jobserver.  When writing
makefiles you must be sure to mark the command as recursive (most
commonly by prefixing the command line with the '+' indicator (*note
Recursive Use of 'make': Recursion.).  Note that the read side of the
jobserver pipe is set to "blocking" mode.  This should not be changed.

   In both implementations of the jobserver, 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; to
release a slot you must write a single character back into the
jobserver.

   It's important that when you release the job slot, you write back the
same character you read.  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:

   * If you 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 does not recognize the format of the
     '--jobserver-auth' string, it should assume the jobserver is using
     a different style and it cannot connect.

   * If your tool determines that the '--jobserver-auth' option
     references a simple pipe 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 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.

   * Your tool may 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
     may want to stop without performing any operations.