github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/user-guide/job-control.md (about)

     1  # Job Control
     2  
     3  > How to manage jobs with Murex
     4  
     5  <h2>Table of Contents</h2>
     6  
     7  <div id="toc">
     8  
     9  - [Overview](#overview)
    10  - [Job Control](#job-control)
    11    - [Listing executions](#listing-executions)
    12    - [Background execution](#background-execution)
    13    - [Foreground execution](#foreground-execution)
    14    - [Suspension](#suspension)
    15    - [Termination](#termination)
    16  
    17  </div>
    18  
    19  
    20  
    21  ## Overview
    22  
    23  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.
    24  
    25  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.
    26  
    27  ## Job Control
    28  
    29  ### Listing executions
    30  
    31  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.
    32  
    33  That includes:
    34  
    35  * any aliases within Murex
    36  * public and private Murex functions
    37  * builtins (eg `fid-list` is a builtin command)
    38  * any external processes that were launched from within this shell session
    39  * any background functions or processes of any of the above
    40  
    41  ```shell
    42  » jobs
    43  PID   State      Background  Process  Parameters
    44  4939  Executing  true        exec     sleep 10000
    45  4996  Executing  true        exec     sleep 10000
    46  5053  Stopped    true        exec     sleep 10000
    47  
    48  » fid-list
    49  PID   State      Background  Process  Parameters
    50  4939  Executing  true        exec     sleep 10000
    51  4996  Executing  true        exec     sleep 10000
    52  5053  Stopped    true        exec     sleep 10000
    53  ```
    54  
    55  Now that we know how to list background jobs, let us review each control operation in more details
    56  
    57  ### Background execution
    58  
    59  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.
    60  
    61  The builtin supports two modes:
    62  
    63  1. It can either be run as a marker which executes the function block in the background
    64  
    65  ```shell
    66  » bg { sleep 5; out "Morning" }
    67  ```
    68  
    69  2. or it can daemonize stopped job and daemonize it.
    70  
    71  ```shell
    72  » jobs
    73  PID   State      Background  Process  Parameters
    74  4939  Executing  true        exec     sleep 10000
    75  4996  Executing  true        exec     sleep 10000
    76  5053  Stopped    true        exec     sleep 10000
    77  
    78  # Run PID 5053 in the background
    79  # Note that `bg` is context aware, hit TAB to visually select the id
    80  » bg 5053
    81  ```
    82  
    83  ### Foreground execution
    84  
    85  Users can bring a background job to the foreground, making it the active task and allowing interaction with it.
    86  
    87  ```shell
    88  # start 3 background jobs
    89  » bg { sleep 10000; out "Task 1" }
    90  » bg { sleep 10000; out "Task 2" }
    91  » bg { sleep 10000; out "Task 3" }
    92  
    93  » jobs
    94  PID   State      Background  Process  Parameters
    95  4939  Executing  true        exec     sleep 10000
    96  4996  Executing  true        exec     sleep 10000
    97  5053  Executing  true        exec     sleep 10000
    98  
    99  # bring back one of them to the foreground, it will block on sleep
   100  # Note that `fg` is context aware, hit TAB to visually select the function id
   101  » fg 5053
   102  ```
   103  
   104  ### Suspension
   105  
   106  Users can suspend and pause the execution of a running job, which will temporarily halt its progress.
   107  
   108  From an interactive session, press `ctrl`+`z` to suspend the currently running job in the foreground.
   109  
   110  ```shell
   111  » sleep 10000; out "Task 1"
   112  # Hit CTRL Z - terminal should allow new inputs
   113  » jobs
   114  PID   State      Background  Process  Parameters
   115  4944  Executing  true        exec     sleep 10000
   116  # Note how the job has a `paused` state
   117  # from there you can resume execution with either `fg` or `bg`
   118  ```
   119  
   120  ### Termination
   121  
   122  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.
   123  
   124  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.
   125  
   126  Alternatively, from a scripting perspective, there are two built-in functions that serve the same purpose: `fid-kill`
   127  
   128  ```shell
   129  » bg { sleep 10000; out "Task 1" }
   130  
   131  » jobs
   132  PID   State      Background  Process  Parameters
   133  4944  Executing  true        exec     sleep 10000
   134  
   135  » fid-kill 4944
   136  Task 1
   137  ```
   138  
   139  ## See Also
   140  
   141  * [Terminal Hotkeys](../user-guide/terminal-keys.md):
   142    A list of all the terminal hotkeys and their uses
   143  * [`bg`](../commands/bg.md):
   144    Run processes in the background
   145  * [`exec`](../commands/exec.md):
   146    Runs an executable
   147  * [`fexec` ](../commands/fexec.md):
   148    Execute a command or function, bypassing the usual order of precedence.
   149  * [`fg`](../commands/fg.md):
   150    Sends a background process into the foreground
   151  * [`fid-kill`](../commands/fid-kill.md):
   152    Terminate a running Murex function
   153  * [`fid-list`](../commands/fid-list.md):
   154    Lists all running functions within the current Murex session
   155  * [`jobs`](../commands/fid-list.md):
   156    Lists all running functions within the current Murex session
   157  
   158  <hr/>
   159  
   160  This document was generated from [gen/user-guide/job-control_doc.yaml](https://github.com/lmorg/murex/blob/master/gen/user-guide/job-control_doc.yaml).