From cb4716df1a9421e87f2994ba047c6eb6f2a81c02 Mon Sep 17 00:00:00 2001 From: Julius Krumbiegel Date: Mon, 24 Mar 2025 11:51:00 +0100 Subject: [PATCH 1/4] Add docs for the new `quarto call engine julia` commands --- docs/computations/julia.qmd | 145 +++++++++++++++++++++++++++++++++++- 1 file changed, 143 insertions(+), 2 deletions(-) diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index 66a21e960a..2c7bdf16f9 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -318,6 +318,147 @@ The currently available options are: - `exeflags`: An array of strings which are appended to the `julia` command that starts the worker process. For example, a notebook is run with `--project=@.` by default (the environment in the directory where the notebook is stored) but this could be overridden by setting `exeflags: ["--project=/some/directory/"]`. - `env`: An array of strings where each string specifies one environment variable that is passed to the worker process. For example, `env: ["SOMEVAR=SOMEVALUE"]`. -### Limitations +### `quarto call engine julia` commands + +Starting with Quarto 1.7, The julia engine offers a couple CLI commands for configuration and monitoring via the `quarto call engine julia` entrypoint. + +#### `status` + +The `status` command prints out information about the currently running server process as well as potential worker processes. The output looks something like this: + +``` +$ quarto call engine julia status +QuartoNotebookRunner server status: + started at: 9:44:31 (47 seconds ago) + runner version: 0.15.0 + environment: /Users/username/Library/Caches/quarto/julia/ + pid: 42008 + port: 8000 + julia version: 1.11.4 + timeout: 5 minutes + workers active: 1 + worker 1: + path: /Users/username/notebook.qmd + run started: 9:44:38 (40 seconds ago) + run finished: - + timeout: 5 minutes + pid: 42026 + exe: `julia` + exeflags: ["--color=yes"] + env: ["JULIA_PROJECT=@."] +``` + +#### `close` + +The `close` command allows shutting down notebook worker processes. +By default, only closing of idle worker processes is allowed. +A worker process is idle when its `run finished` status is populated. In this case, we can call `close` on it: + +``` +$ quarto call engine julia status +QuartoNotebookRunner server status: + started at: 9:44:31 (5 minutes 41 seconds ago) + runner version: 0.15.0 + environment: /Users/username/Library/Caches/quarto/julia/ + pid: 42008 + port: 8000 + julia version: 1.11.4 + timeout: 5 minutes + workers active: 1 + worker 1: + path: /Users/username/notebook.qmd + run started: 9:44:38 (5 minutes 34 seconds ago) + run finished: 9:46:21 (took 1 minute 43 seconds) + timeout: 5 minutes (1 minute 9 seconds left) + pid: 42026 + exe: `julia` + exeflags: ["--color=yes"] + env: ["JULIA_PROJECT=@."] + +$ quarto call engine julia close /Users/username/notebook.qmd +Worker closed successfully. +``` + +To force a busy worker to close, for example if it's stuck in an endless loop or because a computation is taking too long, the `--force` flag can be added. +Using this flag means losing all the work that the worker process has done so far. +At the next run, the worker process will have to be started from scratch and all packages loaded again: + +``` +$ quarto call engine julia status +QuartoNotebookRunner server status: + started at: 11:2:40 (16 seconds ago) + runner version: 0.15.0 + environment: /Users/username/Library/Caches/quarto/julia/ + pid: 50642 + port: 8000 + julia version: 1.11.4 + timeout: 5 minutes + workers active: 1 + worker 1: + path: /Users/username/notebook.qmd + run started: 11:2:47 (9 seconds ago) + run finished: - + timeout: 5 minutes + pid: 50650 + exe: `julia` + exeflags: ["--color=yes"] + env: ["JULIA_PROJECT=@."] + +$ quarto call engine julia close /Users/username/notebook.qmd +ERROR: Julia server returned error after receiving "close" command: + +Failed to close notebook: /Users/username/notebook.qmd + +The underlying Julia error was: + +Tried to close file "/Users/username/notebook.qmd" but the corresponding worker is busy. + +Stack trace: + [omitted for brevity] + +$ quarto call engine julia close --force /Users/username/notebook.qmd +Worker force-closed successfully. + +$ quarto call engine julia status +QuartoNotebookRunner server status: + started at: 11:2:40 (46 seconds ago) + runner version: 0.15.0 + environment: /Users/username/Library/Caches/quarto/julia/ + pid: 50642 + port: 8000 + julia version: 1.11.4 + timeout: 5 minutes (4 minutes 56 seconds left) + workers active: 0 +``` + +#### `stop` + +The `stop` command shuts down the server process gracefully, it will error if any workers are currently busy: + +``` +$ quarto call engine julia status +QuartoNotebookRunner server status: + started at: 11:2:40 (3 minutes 43 seconds ago) + runner version: 0.15.0 + environment: /Users/username/Library/Caches/quarto/julia/ + pid: 50642 + port: 8000 + julia version: 1.11.4 + timeout: 5 minutes (1 minute 59 seconds left) + workers active: 0 + +$ quarto call engine julia stop +Server stopped. + +$ quarto call engine julia status +Julia control server is not running. +``` + +#### `kill` + +The `kill` command shuts the server process down forcefully. This command is intended as a last resort when the server is in a bad state and unresponsive. Note that all worker processes will be killed as well, so you will lose all progress. + +#### `log` + +The `log` command prints the output of the internal log file of the server process. If the server process fails to start or unexpectedly quits, this log file might contain useful information. -Currently, the `engine: julia` option must be specified in each `.qmd` file. Setting the engine project-wide via `_quarto.yml` [is not yet supported](https://github.com/quarto-dev/quarto-cli/issues/3157). From 137ad9531f0a3a9a2a9ae277ecb59e85fff6331a Mon Sep 17 00:00:00 2001 From: Julius Krumbiegel Date: Mon, 31 Mar 2025 10:36:22 +0200 Subject: [PATCH 2/4] remove "a couple" --- docs/computations/julia.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index 2c7bdf16f9..744b8e45d9 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -320,7 +320,7 @@ The currently available options are: ### `quarto call engine julia` commands -Starting with Quarto 1.7, The julia engine offers a couple CLI commands for configuration and monitoring via the `quarto call engine julia` entrypoint. +Starting with Quarto 1.7, The julia engine offers CLI commands for configuration and monitoring via the `quarto call engine julia` entrypoint. #### `status` From e5259fd210c55e156ae00a83d700a35f54f74017 Mon Sep 17 00:00:00 2001 From: Julius Krumbiegel Date: Mon, 31 Mar 2025 10:36:38 +0200 Subject: [PATCH 3/4] "for example" --- docs/computations/julia.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index 744b8e45d9..ac84329d13 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -324,7 +324,7 @@ Starting with Quarto 1.7, The julia engine offers CLI commands for configuration #### `status` -The `status` command prints out information about the currently running server process as well as potential worker processes. The output looks something like this: +The `status` command prints out information about the currently running server process as well as potential worker processes. For example: ``` $ quarto call engine julia status From 5792c4367c004558611dfcdccbf15a10a1b23ffe Mon Sep 17 00:00:00 2001 From: Julius Krumbiegel Date: Mon, 31 Mar 2025 10:37:38 +0200 Subject: [PATCH 4/4] rework sentence --- docs/computations/julia.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index ac84329d13..c0b338dd0f 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -433,7 +433,7 @@ QuartoNotebookRunner server status: #### `stop` -The `stop` command shuts down the server process gracefully, it will error if any workers are currently busy: +The `stop` command shuts down the server process gracefully. Note that you will get an error if any workers are currently busy: ``` $ quarto call engine julia status