From 596f47a11c05ac07b74c62c10063a76d3fe5bdad Mon Sep 17 00:00:00 2001 From: rillig Date: Sun, 27 Sep 2020 23:12:12 +0000 Subject: [PATCH] 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. --- usr.bin/make/job.h | 73 +++++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/usr.bin/make/job.h b/usr.bin/make/job.h index 4f453b49d97a..56b082aa3909 100644 --- a/usr.bin/make/job.h +++ b/usr.bin/make/job.h @@ -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, int timeout); */ #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;