diff --git a/book/background_jobs.md b/book/background_jobs.md new file mode 100644 index 00000000000..2f5828de7ff --- /dev/null +++ b/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 Ctrl+Z. 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`. diff --git a/book/background_task.md b/book/background_task.md deleted file mode 100644 index e99b2581361..00000000000 --- a/book/background_task.md +++ /dev/null @@ -1,34 +0,0 @@ -# Background Tasks with Nu - -Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples: - -1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue) -2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/) - -## Using Nu With Pueue - -The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc) - -Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily. - -Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier. - -Here is a setup example to make Nushell "support" background tasks: - -1. Install pueue -2. run `pueued`, you can refer to [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) for more information. -3. Put the [task.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/task.nu) file under `$env.NU_LIB_DIRS`. -4. Add a line to the `$nu.config-path` file: `use task.nu` -5. Restart Nushell. - -Then you will get some commands to schedule background tasks. (e.g: `task spawn`, `task status`, `task log`) - -Cons: It spawns a new Nushell interpreter to execute every single task, so it doesn't inherit current scope's variables, custom commands, alias definition. -It only inherits environment variables whose value can be converted to a string. -Therefore, if you want to use custom commands or variables, you have to [`use`](/commands/docs/use.md) or [`def`](/commands/docs/def.md) them within the given block. - -## Using Nu With Terminal Multiplexer - -You can choose and install a terminal multiplexer and use it. - -It allows you to easily switch between multiple programs in one terminal, detach them (they continue to run in the background) and reconnect them to a different terminal. As a result, it is very flexible and usable. diff --git a/book/nu_as_a_shell.md b/book/nu_as_a_shell.md index 7f457ac9072..4b31e6c04e3 100644 --- a/book/nu_as_a_shell.md +++ b/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. diff --git a/de/book/background_task.md b/de/book/background_jobs.md similarity index 99% rename from de/book/background_task.md rename to de/book/background_jobs.md index 0c89c6bddfd..1e1b764f74b 100644 --- a/de/book/background_task.md +++ b/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`. diff --git a/de/book/nu_as_a_shell.md b/de/book/nu_as_a_shell.md index 8357c8c3c13..b3605767f89 100644 --- a/de/book/nu_as_a_shell.md +++ b/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. diff --git a/tools/i18n-meta.json b/tools/i18n-meta.json index 0bc38df95ba..0c6f4151ec7 100644 --- a/tools/i18n-meta.json +++ b/tools/i18n-meta.json @@ -48,7 +48,7 @@ "ru": "-" }, { - "name": "background_task.md", + "name": "background_jobs.md", "en": "In progress", "zh-CN": "-", "fr": "-",