Add docs for jobs

book/background_jobs.md

@@ -0,0 +1,107 @@
+# Background Jobs
+
+Nushell currently has experimental support for thread-based background jobs.
+
+## Spawning Jobs
+
+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
+an unique integer id for the spawned job:
+
+```nu
+'i am' | save status.txt
+
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+# => 1
+
+open status.txt
+# => i am
+
+# wait for 10 seconds
+sleep 10sec
+
+open status.txt
+# => i am inevitable
+```
+
+## Listing and Killing jobs
+
+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.
+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:
+
+```nu
+let id = job spawn { sleep 1day }
+
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ thread ┃ [list 0 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+
+job kill $id
+
+job list
+# => ╭────────────╮
+# => │ empty list │
+# => ╰────────────╯
+```
+
+## Job suspension
+
+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:
+
+```nu
+long_running_process # this starts running, then Ctrl+Z is pressed
+# => Job 1 is frozen
+
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ frozen ┃ [list 1 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+```
+
+A frozen job can be brought back into foreground with the [`job unfreeze`](/commands/docs/job_unfreeze.md) command:
+
+```nu
+job unfreeze
+# process is brought back where it stopped
+```
+
+::: tip Tip
+For those familiar with other Unix shells, you can create an alias to emulate the behavior of the `fg` command:
+
+```nu
+alias fg = job unfreeze
+```
+
+:::
+
+By default, `job unfreeze` will unfreeze the most recently frozen job. However, you can also specify the id of a specific job to unfreeze:
+
+```nu
+vim
+# => Job 1 is frozen
+
+long_running_process
+# => Job 2 is frozen
+
+job unfreeze 1
+# we're back in vim
+```
+
+## Exit Behavior
+
+Unlike many other shells, Nushell jobs are **not** separate processes,
+and are instead implemented as background threads.
+
+An important side effect of this, is that all background jobs will terminate once the shell
+process exits.
+For this reason, Nushell has no UNIX-like `disown` command to prevent jobs from terminating once the shell exits.
+To account for that, there are plans for a `job dispatch` implementation in the future,
+for spawning independent background processes.
+
+Additionally, if the user is running an interactive Nushell session and runs
+[`exit`](/commands/docs/exit.md) while there are background jobs running,
+the shell will warn about them before prompting the user to confirm `exit`.

book/nu_as_a_shell.md

@@ -23,6 +23,6 @@ It is also possible to define [custom signatures for external commands](externs.
 
 [Coloring and Theming in Nu](coloring_and_theming.md) goes into more detail about how to configure Nushell's appearance.
 
-If you want to schedule some commands to run in the background, [Background task in Nu](background_task.md) provides simple guidelines for you to follow.
+If you want to schedule some commands to run in the background, [Background jobs](background_jobs.md) provides simple guidelines for you to follow.
 
 Finally, [hooks](hooks.md) allow you to insert fragments of Nushell code to run at certain events.

de/book/background_task.md → de/book/background_jobs.md

@@ -17,6 +17,7 @@ Den Status von Tasks erhält man sehr einfach.
 Hier ein einfaches Beispiel wie ein [nushell module](https://github.com/nushell/nu_scripts/tree/main/background_task) mit pueu zusammenarbeitet.
 
 Das Setup umfasst:
+
 1. installiere pueue
 2. führe `pueued` mit der default Konfiguration aus. Siehe unter [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) für mehr Informationen.
 3. speichere die [job.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/job.nu) Datei unter `$env.NU_LIB_DIRS`.

de/book/nu_as_a_shell.md

@@ -25,6 +25,6 @@ Es ist auch möglich, eigene [Signaturen für externe Befehle (EN)](/book/extern
 
 [Farben und Themen in Nu](coloring_and_theming.md)) geht ins Detail zum Thema, wie Nushells Aussehen konfiguriert werden kann.
 
-Sind einige Befehle geplant , die im Hintergrund ablaufen sollen, so kann darüber in [Hintergrund Tasks in Nu](background_task.md) nachgelesen werden.
+Sind einige Befehle geplant , die im Hintergrund ablaufen sollen, so kann darüber in [Hintergrund Tasks in Nu](background_jobs.md) nachgelesen werden.
 
 Schliesslich erklärt [Hooks](hooks.md) wie Fragmente von Nushell Code beim Auftreten gewisser Ereignisse ausgeführt werden kann.

tools/i18n-meta.json

@@ -48,7 +48,7 @@
     "ru": "-"
   },
   {
-    "name": "background_task.md",
+    "name": "background_jobs.md",
     "en": "In progress",
     "zh-CN": "-",
     "fr": "-",