From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: zsh-workers-return-43570-ml=inbox.vuxu.org@zsh.org X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.1 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from primenet.com.au (ns1.primenet.com.au [203.24.36.2]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 9fde8ccd for ; Thu, 27 Sep 2018 15:52:19 +0000 (UTC) Received: (qmail 1153 invoked by alias); 27 Sep 2018 15:52:02 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: List-Unsubscribe: X-Seq: 43570 Received: (qmail 1680 invoked by uid 1010); 27 Sep 2018 15:52:01 -0000 X-Qmail-Scanner-Diagnostics: from out1-smtp.messagingengine.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.99.2/21882. spamassassin: 3.4.1. Clear:RC:0(66.111.4.25):SA:0(-2.6/5.0):. Processed in 7.055567 secs); 27 Sep 2018 15:52:01 -0000 X-Envelope-From: d.s@daniel.shahaf.name X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= daniel.shahaf.name; h=date:from:in-reply-to:message-id :references:subject:to:x-me-sender:x-me-sender:x-sasl-enc; s= fm1; bh=2d6a7bSXwslkvW0z5zo63Kb1a+9ty0KoUDIE0DtjMWY=; b=DDLpDpcr PX24F04NxqgmBWzNP+pVbKPQxBc59Dcj9SC9UtONvxoOLLCD32LUXwRBC28bS+Bm 03KTJFX02RuAqbq7XNplai7kzDQi6+FwlDdhmZFbIIv6bF0X29Vv9wlWLRnzHRpa p8TwJEBFFfTQuWgv2gbmX0Byt2WkWERnXSuXiy8/8LQUnT+MpSFqLZZIRoxgnxm5 VBdk5Yoo0i5DeZdeGhBLH1x79cQLCMlW4ag3ckSdhYAhewaaCBJBSSibDFsBL3n9 O+hrL4xXXr0uw0OFdHcKWld6m5se7Y7/+5v0etiK7fU8aaLubYbTm9+lYWalAxFy v5bDtI1lzYx6zA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=date:from:in-reply-to:message-id :references:subject:to:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; bh=2d6a7bSXwslkvW0z5zo63Kb1a+9ty0KoUDIE0DtjMWY=; b=e7juFmIW RLOfv+y73clkhyku9qy8iA0hv1l/bh1bFzCY/OakMxextV7ZTLi2mKD7YMwbFmmY DJ5JpcDnvD6QrPImJom1ksr5TdEc+iBG1jiS723QSvD2qcJQ/koN8KDuQFbjOG05 ZNAYhCgofZpBap3odyR/XGFUm1JhYFRexyOHLVu620w4rysQvydtfPMeIOn/qQOT a1513S/Lrx9iXWpTgQfqGnDV4tL3XjY8KpLhK3juxgyCx860LknA/KoVwHv4NFqH le0J9kg1ydUeC3tEsYwcrfVWtxOvqVZa/LzreW6tsBAsP6pAWrzItGMUddVpSgfB K8umpbPaoKYFDw== X-ME-Proxy: X-ME-Sender: From: Daniel Shahaf To: zsh-workers@zsh.org Subject: [PATCH] Start documenting jobs.c, in particular superjobs. Date: Thu, 27 Sep 2018 15:51:20 +0000 Message-Id: <20180927155120.1434-1-danielsh@tarpaulin.shahaf.local2> X-Mailer: git-send-email 2.11.0 In-Reply-To: References: --- Src/jobs.c | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/Src/jobs.c b/Src/jobs.c index 8103f5c92..c15001d6b 100644 --- a/Src/jobs.c +++ b/Src/jobs.c @@ -30,6 +30,27 @@ #include "zsh.mdh" #include "jobs.pro" +/* + * Job control in zsh + * ================== + * + * A 'job' represents a pipeline; see the section JOBS in zshmisc(1)) for an + * introduction. The 'struct job's are allocated in the array 'jobtab' which + * has 'jobtabsize' elements. The job whose processes we are currently + * preparing to execute is identified by the global variable 'thisjob'. + * + * A 'superjob' is a job that represents a complex shell construct that has been + * backgrounded. For example, if one runs '() { vi; echo }', a job is created + * for the pipeline 'vi'. If one then backgrounds vi (with ^Z / SIGTSTP), + * the shell forks; the parent shell returns to the interactive prompt and + * the child shell becomes a new job in the parent shell. The job representing + * the child shell to the parent shell is a superjob (STAT_SUPERJOB); the 'vi' + * job is marked as a subjob (STAT_SUBJOB) in the parent shell. When the child + * shell is resumed (with fg / SIGCONT), it forwards the signal to vi and, + * after vi exits, continues executing the remainder of the function. + * (See workers/43565.) + */ + /* the process group of the shell at startup (equal to mypgprp, except when we started without being process group leader */ @@ -46,17 +67,17 @@ mod_export pid_t mypgrp; /**/ pid_t last_attached_pgrp; -/* the job we are working on */ +/* the job we are working on, or -1 if none */ /**/ mod_export int thisjob; -/* the current job (+) */ +/* the current job (%+) */ /**/ mod_export int curjob; -/* the previous job (-) */ +/* the previous job (%-) */ /**/ mod_export int prevjob;