Merge branch 'document-jobserver-fds'

1 files changed, 45 insertions, 45 deletions

diff --git a/make.1 b/make.1
index b61a5ad9..4192f247 100644
--- a/make.1
+++ b/make.1
@@ -373,67 +373,67 @@ programs are properly installed at your site, the command
 .PP
 should give you access to the complete manual.
 .SH "PARALLEL MAKE AND THE JOBSERVER"
-GNU make can invoke multiple commands, or
-.I jobs,
-in parallel.
+Using the
+.I -j
+option, the user can instruct
 .BR make
-may be told to run at most
-.B N
-jobs in parallel, where it will invoke between
-1 and
-.B N
-jobs, but never more than
-.B N.
+to execute tasks in parallel. By specifying a numeric argument to
+.I -j
+the user may specify an upper limit of the number of parallel tasks to
+be run.
 .PP
-In a recursive build environment, no one instance of
+When the build environment is such that a top level
 .BR make
-has enough information, enough
-.I global vision,
-to be able to know how many jobs are being run at any given moment across all the
-other instances of
-.BR make.
-.PP
-Rather than using complex schemes such as a central server, shared
-memory, sockets, etc. for synchronizing the various instances of make,
+invokes
+.BR sub-makes
+(for instance, a style in which each sub-directory contains its own
+.I Makefile
+), no individual instance of
+.BR make
+knows how many tasks are running in parallel, so keeping the number of
+tasks under the upper limit would be impossible without communication
+between all the
 .BR make
-uses a simple  pipe. The initial, top-level
+instances running. While solutions like having the top level
 .BR make
-creates a pipe and writes
+serve as a central controller are feasible, or using other
+synchronization mechanisms like shared memory or sockets can be
+created, the current implementation uses a simple shared pipe.
+.PP
+This pipe is created by the top-level
+.BR make
+process, and passed on to all the
+.BR sub-makes.
+The top level
+.BR make process writes
 .B N-1
 one-byte tokens into the pipe (The top level
 .BR make
-is assumed to reserve one token for iitself). That pipe is shared
-between that
+is assumed to reserve one token for itself). Whenever any of the
+.BR make
+processes (including the top-level
+.BR make
+) needs to run a new task, it reads a byte from the shared pipe. If
+there are no tokens left, it must wait for a token to be written back
+to the pipe. Once the task is completed, the
 .BR make
-and all
-.BR submakes,
-and any time any
+process writes a token back to the pipe (and thus, if the tokens had
+been exhausted, unblocking the first
 .BR make
-wants to run
-a job it first has to read a token from the pipe. Once the job is
-complete, it writes the token back to the pipe. Since there are only
+process that was waiting to read a token).  Since only
 .B N-1
-tokens, you know that you will never invoke more than
+tokens were written into the pipe, no more than
 .B N
-jobs.
+tasks can be running at any given time.
 .PP
 If the job to be run is not a
 .BR sub-make
-(determined the same way GNU
-make has always done so: by the absence of both the
-.B MAKE
-variable in the command script and the special prefix
-.B +
-before a line in the
-command script), then
+then
 .BR make
-will close the jobserver pipe file
-descriptors before invoking the commands. This ensures that no other
-commands will interrupt the jobserver processing, and it also ensures
-that commands that expect certain file
-descriptors to be available will not be disappointed. More details are
-available at
-.IR http://make.mad-scientist.net/papers/jobserver-implementation/
+will close the jobserver pipe file descriptors before invoking the
+commands, so that the command can not interfere with the
+.I jobserver,
+and the command does not find any unusual file descriptors.
 .SH BUGS
 See the chapter ``Problems and Bugs'' in
 .IR "The GNU Make Manual" .