Module Name: src
Committed By: rillig
Date: Sun Sep 27 23:12:12 UTC 2020
Modified Files:
src/usr.bin/make: job.h
Log Message:
make(1): rewrite documentation of Job
The comment above a struct is supposed to give a high-level overview.
The previous comment didn't do that but instead listed the struct fields
in declaration order in a numbered list, which was not helpful.
To generate a diff of this commit:
cvs rdiff -u -r1.51 -r1.52 src/usr.bin/make/job.h
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/make/job.h
diff -u src/usr.bin/make/job.h:1.51 src/usr.bin/make/job.h:1.52
--- src/usr.bin/make/job.h:1.51 Sun Sep 27 21:35:16 2020
+++ src/usr.bin/make/job.h Sun Sep 27 23:12:12 2020
@@ -1,4 +1,4 @@
-/* $NetBSD: job.h,v 1.51 2020/09/27 21:35:16 rillig Exp $ */
+/* $NetBSD: job.h,v 1.52 2020/09/27 23:12:12 rillig Exp $ */
/*
* Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -73,10 +73,10 @@
* from: @(#)job.h 8.1 (Berkeley) 6/6/93
*/
-/*-
- * job.h --
- * Definitions pertaining to the running of jobs in parallel mode.
+/*
+ * Running of jobs in parallel mode.
*/
+
#ifndef MAKE_JOB_H
#define MAKE_JOB_H
@@ -110,28 +110,6 @@ emul_poll(struct pollfd *fd, int nfd, in
*/
#define POLL_MSEC 5000
-/*-
- * Job Table definitions.
- *
- * Each job has several things associated with it:
- * 1) The process id of the child shell
- * 2) The graph node describing the target being made by this job
- * 3) A LstNode for the first command to be saved after the job
- * completes. This is NULL if there was no "..." in the job's
- * commands.
- * 4) An FILE* for writing out the commands. This is only
- * used before the job is actually started.
- * 5) The output is being caught via a pipe and
- * the descriptors of our pipe, an array in which output is line
- * buffered and the current position in that buffer are all
- * maintained for each job.
- * 6) A word of flags which determine how the module handles errors,
- * echoing, etc. for the job
- *
- * When a job is finished, the Make_Update function is called on each of the
- * parents of the node which was just remade. This takes care of the upward
- * traversal of the dependency graph.
- */
struct pollfd;
@@ -139,21 +117,43 @@ struct pollfd;
# include "meta.h"
#endif
-#define JOB_BUFSIZE 1024
+/* A Job manages the shell commands that are run to create a single target.
+ * Each job is run in a separate subprocess by a shell. Several jobs can run
+ * in parallel.
+ *
+ * The shell commands for the target are written to a temporary file,
+ * then the shell is run with the temporary file as stdin, and the output
+ * of that shell is captured via a pipe.
+ *
+ * When a job is finished, Make_Update updates all parents of the node
+ * that was just remade, marking them as ready to be made next if all
+ * other dependencies are finished as well. */
typedef struct Job {
- int pid; /* The child's process ID */
- GNode *node; /* The target the child is making */
- StringListNode *tailCmds; /* The node of the first command to be
- * saved when the job has been run */
- FILE *cmdFILE; /* When creating the shell script, this is
- * where the commands go */
+ /* The process ID of the shell running the commands */
+ int pid;
+
+ /* The target the child is making */
+ GNode *node;
+
+ /* If one of the shell commands is "...", all following commands are
+ * delayed until the .END node is made. This list node points to the
+ * first of these commands, if any. */
+ StringListNode *tailCmds;
+
+ /* When creating the shell script, this is where the commands go.
+ * This is only used before the job is actually started. */
+ FILE *cmdFILE;
+
int exit_status; /* from wait4() in signal handler */
+
char job_state; /* status of the job entry */
#define JOB_ST_FREE 0 /* Job is available */
#define JOB_ST_SETUP 1 /* Job is allocated but otherwise invalid */
#define JOB_ST_RUNNING 3 /* Job is running, pid valid */
#define JOB_ST_FINISHED 4 /* Job is done (ie after SIGCHILD) */
+
char job_suspended;
+
short flags; /* Flags to control treatment of job */
#define JOB_IGNERR 0x001 /* Ignore non-zero exits */
#define JOB_SILENT 0x002 /* no output */
@@ -165,10 +165,11 @@ typedef struct Job {
int jobPipe[2]; /* Pipe for reading output from job */
struct pollfd *inPollfd; /* pollfd associated with inPipe */
+
+#define JOB_BUFSIZE 1024
+ /* Buffer for storing the output of the job, line by line. */
char outBuf[JOB_BUFSIZE + 1];
- /* Buffer for storing the output of the
- * job, line by line */
- int curPos; /* Current position in op_outBuf */
+ int curPos; /* Current position in outBuf. */
#ifdef USE_META
struct BuildMon bm;
