github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/gen/user-guide/job-control.inc.md (about) 1 {{ if env "DOCGEN_TARGET=" }}<h2>Table of Contents</h2> 2 3 <div id="toc"> 4 5 - [Overview](#overview) 6 - [Job Control](#job-control) 7 - [Listing executions](#listing-executions) 8 - [Background execution](#background-execution) 9 - [Foreground execution](#foreground-execution) 10 - [Suspension](#suspension) 11 - [Termination](#termination) 12 13 </div> 14 15 {{ end }} 16 17 ## Overview 18 19 Job control is a feature that allows users to manage and control multiple executions in a terminal session, it is particularly useful when working with simultaneous jobs as it provides users with the ability to start, stop, pause, resume, and manage the execution. 20 21 Murex is very similar to other shells, with the single particularity: builtins are not forked processes like in a traditional POSIX shell but rather virtual threads. This means that you cannot use the typical operating systems command `ps` to list Murex functions. 22 23 ## Job Control 24 25 ### Listing executions 26 27 This is where `fid-list` (or its alias `jobs`) comes into play. The builtin is used to view all the functions and processes that are managed by the current session. 28 29 That includes: 30 31 * any aliases within Murex 32 * public and private Murex functions 33 * builtins (eg `fid-list` is a builtin command) 34 * any external processes that were launched from within this shell session 35 * any background functions or processes of any of the above 36 37 ```shell 38 » jobs 39 PID State Background Process Parameters 40 4939 Executing true exec sleep 10000 41 4996 Executing true exec sleep 10000 42 5053 Stopped true exec sleep 10000 43 44 » fid-list 45 PID State Background Process Parameters 46 4939 Executing true exec sleep 10000 47 4996 Executing true exec sleep 10000 48 5053 Stopped true exec sleep 10000 49 ``` 50 51 Now that we know how to list background jobs, let us review each control operation in more details 52 53 ### Background execution 54 55 Users can easilly start a process in the background with the `bg` builtin. `bg` allows to continue working on other tasks while the process runs independently. 56 57 The builtin supports two modes: 58 59 1. It can either be run as a marker which executes the function block in the background 60 61 ```shell 62 » bg { sleep 5; out "Morning" } 63 ``` 64 65 2. or it can daemonize stopped job and daemonize it. 66 67 ```shell 68 » jobs 69 PID State Background Process Parameters 70 4939 Executing true exec sleep 10000 71 4996 Executing true exec sleep 10000 72 5053 Stopped true exec sleep 10000 73 74 # Run PID 5053 in the background 75 # Note that `bg` is context aware, hit TAB to visually select the id 76 » bg 5053 77 ``` 78 79 ### Foreground execution 80 81 Users can bring a background job to the foreground, making it the active task and allowing interaction with it. 82 83 ```shell 84 # start 3 background jobs 85 » bg { sleep 10000; out "Task 1" } 86 » bg { sleep 10000; out "Task 2" } 87 » bg { sleep 10000; out "Task 3" } 88 89 » jobs 90 PID State Background Process Parameters 91 4939 Executing true exec sleep 10000 92 4996 Executing true exec sleep 10000 93 5053 Executing true exec sleep 10000 94 95 # bring back one of them to the foreground, it will block on sleep 96 # Note that `fg` is context aware, hit TAB to visually select the function id 97 » fg 5053 98 ``` 99 100 ### Suspension 101 102 Users can suspend and pause the execution of a running job, which will temporarily halt its progress. 103 104 From an interactive session, press `ctrl`+`z` to suspend the currently running job in the foreground. 105 106 ```shell 107 » sleep 10000; out "Task 1" 108 # Hit CTRL Z - terminal should allow new inputs 109 » jobs 110 PID State Background Process Parameters 111 4944 Executing true exec sleep 10000 112 # Note how the job has a `paused` state 113 # from there you can resume execution with either `fg` or `bg` 114 ``` 115 116 ### Termination 117 118 Last but not least, users have the option to terminate or halt an execution. This action can be carried out interactively or through built-in functions. 119 120 When running an execution in the foreground from an interactive shell, simply press `ctrl`+`c` to terminate the process. This method is straightforward and efficient. 121 122 Alternatively, from a scripting perspective, there are two built-in functions that serve the same purpose: `fid-kill` 123 124 ```shell 125 » bg { sleep 10000; out "Task 1" } 126 127 » jobs 128 PID State Background Process Parameters 129 4944 Executing true exec sleep 10000 130 131 » fid-kill 4944 132 Task 1 133 ```