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  ```