|
| 1 | +# Background Jobs |
| 2 | + |
| 3 | +Nushell currently has experimental support for thread-based background jobs. |
| 4 | + |
| 5 | +## Spawning Jobs |
| 6 | + |
| 7 | +Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning |
| 8 | +an unique integer id for the spawned job: |
| 9 | + |
| 10 | +```nu |
| 11 | +'i am' | save status.txt |
| 12 | +
|
| 13 | +job spawn { sleep 10sec; ' inevitable' | save --append status.txt } |
| 14 | +# => 1 |
| 15 | +
|
| 16 | +open status.txt |
| 17 | +# => i am |
| 18 | +
|
| 19 | +# wait for 10 seconds |
| 20 | +sleep 10sec |
| 21 | +
|
| 22 | +open status.txt |
| 23 | +# => i am inevitable |
| 24 | +``` |
| 25 | + |
| 26 | +## Listing and Killing jobs |
| 27 | + |
| 28 | +Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing. |
| 29 | +Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes: |
| 30 | + |
| 31 | +```nu |
| 32 | +let id = job spawn { sleep 1day } |
| 33 | +
|
| 34 | +job list |
| 35 | +# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓ |
| 36 | +# => ┃ # ┃ id ┃ type ┃ pids ┃ |
| 37 | +# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫ |
| 38 | +# => ┃ 0 ┃ 1 ┃ thread ┃ [list 0 items] ┃ |
| 39 | +# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛ |
| 40 | +
|
| 41 | +job kill $id |
| 42 | +
|
| 43 | +job list |
| 44 | +# => ╭────────────╮ |
| 45 | +# => │ empty list │ |
| 46 | +# => ╰────────────╯ |
| 47 | +``` |
| 48 | + |
| 49 | +## Job suspension |
| 50 | + |
| 51 | +On Unix targets, such as Linux and macOS, Nushell also supports suspending external commands using <kbd>Ctrl</kbd>+<kbd>Z</kbd>. When a running process is suspended, it is turned into a "frozen" background job: |
| 52 | + |
| 53 | +```nu |
| 54 | +long_running_process # this starts running, then Ctrl+Z is pressed |
| 55 | +# => Job 1 is frozen |
| 56 | +
|
| 57 | +job list |
| 58 | +# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓ |
| 59 | +# => ┃ # ┃ id ┃ type ┃ pids ┃ |
| 60 | +# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫ |
| 61 | +# => ┃ 0 ┃ 1 ┃ frozen ┃ [list 1 items] ┃ |
| 62 | +# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛ |
| 63 | +``` |
| 64 | + |
| 65 | +A frozen job can be brought back into foreground with the [`job unfreeze`](/commands/docs/job_unfreeze.md) command: |
| 66 | + |
| 67 | +```nu |
| 68 | +job unfreeze |
| 69 | +# process is brought back where it stopped |
| 70 | +``` |
| 71 | + |
| 72 | +::: tip Tip |
| 73 | +For those familiar with other Unix shells, you can create an alias to emulate the behavior of the `fg` command: |
| 74 | + |
| 75 | +```nu |
| 76 | +alias fg = job unfreeze |
| 77 | +``` |
| 78 | + |
| 79 | +::: |
| 80 | + |
| 81 | +By default, `job unfreeze` will unfreeze the most recently frozen job. However, you can also specify the id of a specific job to unfreeze: |
| 82 | + |
| 83 | +```nu |
| 84 | +vim |
| 85 | +# => Job 1 is frozen |
| 86 | +
|
| 87 | +long_running_process |
| 88 | +# => Job 2 is frozen |
| 89 | +
|
| 90 | +job unfreeze 1 |
| 91 | +# we're back in vim |
| 92 | +``` |
| 93 | + |
| 94 | +## Exit Behavior |
| 95 | + |
| 96 | +Unlike many other shells, Nushell jobs are **not** separate processes, |
| 97 | +and are instead implemented as background threads. |
| 98 | + |
| 99 | +An important side effect of this, is that all background jobs will terminate once the shell |
| 100 | +process exits. |
| 101 | +For this reason, Nushell has no UNIX-like `disown` command to prevent jobs from terminating once the shell exits. |
| 102 | +To account for that, there are plans for a `job dispatch` implementation in the future, |
| 103 | +for spawning independent background processes. |
| 104 | + |
| 105 | +Additionally, if the user is running an interactive Nushell session and runs |
| 106 | +[`exit`](/commands/docs/exit.md) while there are background jobs running, |
| 107 | +the shell will warn about them before prompting the user to confirm `exit`. |
0 commit comments