Pure decisions for choosing and launching a worker runtime: which
runtime to use, which JVM options to pass on to JVM workers, how many
workers to start by default, which deps.edn aliases to put on the
classpath, and what to key a cached classpath on. The shell
(volley.shell.runtime) gathers the inputs and does the I/O.
Pure decisions for choosing and launching a worker runtime: which runtime to use, which JVM options to pass on to JVM workers, how many workers to start by default, which deps.edn aliases to put on the classpath, and what to key a cached classpath on. The shell (`volley.shell.runtime`) gathers the inputs and does the I/O.
(alias-jvm-opts deps-text aliases)The :jvm-opts of aliases in deps.edn (text, or nil), in alias order.
clojure -Spath does not report them, and the Clojure CLI would pass
them to the JVM when running the alias, so JVM workers started from a
babashka parent get them here.
The `:jvm-opts` of `aliases` in deps.edn (text, or nil), in alias order. `clojure -Spath` does not report them, and the Clojure CLI would pass them to the JVM when running the alias, so JVM workers started from a babashka parent get them here.
(cache-file key)Where the classpath for key is cached.
Where the classpath for `key` is cached.
(choose-aliases requested deps-text)The aliases for clojure -Spath: the explicit requested ones, else
[:test] when deps.edn (text, or nil when missing) defines a :test
alias, else none.
The aliases for `clojure -Spath`: the explicit `requested` ones, else `[:test]` when deps.edn (text, or nil when missing) defines a `:test` alias, else none.
(classpath-key deps-text aliases)(classpath-key deps-text aliases others)Cache key for a computed classpath: a SHA-256 of the deps.edn text
(nil when missing), the aliases and the other deps.edn files the
classpath depends on ({path text-or-nil}: local roots, the user's),
shortened to 16 hex characters. Equal inputs give equal keys; changing
any text, any path or the aliases changes it.
Cache key for a computed classpath: a SHA-256 of the deps.edn text
(nil when missing), the aliases and the other deps.edn files the
classpath depends on (`{path text-or-nil}`: local roots, the user's),
shortened to 16 hex characters. Equal inputs give equal keys; changing
any text, any path or the aliases changes it.Options every JVM worker starts with, before the forwarded ones, so a
forwarded option for the same setting wins. Test runs are short, and
limiting the JIT to the C1 compiler cuts about a fifth off a typical
suite's wall time (no wait for C2 compilation); a suite that is mostly
long CPU-bound loops can pass -XX:TieredStopAtLevel=4 to undo it.
Options every JVM worker starts with, before the forwarded ones, so a forwarded option for the same setting wins. Test runs are short, and limiting the JIT to the C1 compiler cuts about a fifth off a typical suite's wall time (no wait for C2 compilation); a suite that is mostly long CPU-bound loops can pass `-XX:TieredStopAtLevel=4` to undo it.
(default-workers runtime cpus)Default worker count: the CPU count, capped at 8 on babashka and at 4 on the JVM, where every worker is a full JVM with the project loaded.
Default worker count: the CPU count, capped at 8 on babashka and at 4 on the JVM, where every worker is a full JVM with the project loaded.
(forward-jvm-args input-args)The parent JVM's input arguments (RuntimeMXBean.getInputArguments)
that JVM workers should start with. Everything is forwarded (heap size,
GC and -XX flags, -D properties, --add-opens, agents) except
debugger agents, JMX remote ports, socket REPL properties, JFR and
unified logging, files that would collide (error file, heap dump path)
and class path options, since workers get their own classpath.
The parent JVM's input arguments (`RuntimeMXBean.getInputArguments`) that JVM workers should start with. Everything is forwarded (heap size, GC and `-XX` flags, `-D` properties, `--add-opens`, agents) except debugger agents, JMX remote ports, socket REPL properties, JFR and unified logging, files that would collide (error file, heap dump path) and class path options, since workers get their own classpath.
(heuristic-run? {:keys [parent runtime workers-set? watch? isolate?]})True when worker-plan decides how run mode gets its workers: a JVM
parent (:parent) with JVM workers (:runtime), the default worker
count (no :workers-set?), and neither :watch? nor :isolate?. Its
wall time then measures the setup the next plan chooses between.
True when `worker-plan` decides how run `mode` gets its workers: a JVM parent (`:parent`) with JVM workers (`:runtime`), the default worker count (no `:workers-set?`), and neither `:watch?` nor `:isolate?`. Its wall time then measures the setup the next plan chooses between.
(hook-namespaces msg)Namespaces of the hooks, worker setup fns and reporters a worker
resolves from the :configure message msg.
Namespaces of the hooks, worker setup fns and reporters a worker resolves from the `:configure` message `msg`.
The longest run that is worth running inside the parent JVM. A JVM
worker costs about half a second to start and loads the project's code
again, which a run of a few seconds never wins back; past this, parallel
workers can. An in-process run that is still going after this long
starts worker processes for the namespaces left (volley.engine).
The longest run that is worth running inside the parent JVM. A JVM worker costs about half a second to start and loads the project's code again, which a run of a few seconds never wins back; past this, parallel workers can. An in-process run that is still going after this long starts worker processes for the namespaces left (`volley.engine`).
(in-process-ok? mode plan configure has-ns?)Whether plan can run on a thread of the parent: mode is a
heuristic-run?, and every planned or preloaded namespace, and every
namespace a hook or reporter of :configure names, has a source file
where a worker would find it by (has-ns? ns-sym): on the parent's
classpath or under a suite's test path, which an in-process worker adds
to the parent's classpath as a JVM worker's has them.
Whether `plan` can run on a thread of the parent: `mode` is a `heuristic-run?`, and every planned or preloaded namespace, and every namespace a hook or reporter of `:configure` names, has a source file where a worker would find it by `(has-ns? ns-sym)`: on the parent's classpath or under a suite's test path, which an in-process worker adds to the parent's classpath as a JVM worker's has them.
(invocation {:keys [command bb? task aliases main-opts]})How the user ran volley, for the command in the rerun hint: command
(the VOLLEY_COMMAND environment variable, which bin/volley sets), else
bb <task> inside a babashka task, else bb -m volley.main on babashka,
else the Clojure CLI with the aliases of the JVM's basis (and -m volley.main unless one of them runs it through :main-opts).
How the user ran volley, for the command in the rerun hint: `command` (the `VOLLEY_COMMAND` environment variable, which `bin/volley` sets), else `bb <task>` inside a babashka task, else `bb -m volley.main` on babashka, else the Clojure CLI with the aliases of the JVM's basis (and `-m volley.main` unless one of them runs it through `:main-opts`).
(join-classpath entries sep)Entries joined into a classpath, first occurrence of each kept.
Entries joined into a classpath, first occurrence of each kept.
(jvm-worker-command {:keys [java jvm-args classpath]})argv for a JVM worker: the java executable, default-jvm-args, the
forwarded JVM options, the classpath, and clojure.main -m volley.shell.worker.
argv for a JVM worker: the `java` executable, `default-jvm-args`, the forwarded JVM options, the classpath, and `clojure.main -m volley.shell.worker`.
(local-deps-files deps-text dir {:keys [read join]})Every deps.edn reachable from deps-text (the project's, in directory
dir) through :local/root, transitively, as {path text-or-nil}.
read takes a path and returns its text or nil; join resolves a root
against the directory of the deps.edn that names it. A cycle of local
roots ends where it repeats.
Every deps.edn reachable from `deps-text` (the project's, in directory
`dir`) through `:local/root`, transitively, as `{path text-or-nil}`.
`read` takes a path and returns its text or nil; `join` resolves a root
against the directory of the deps.edn that names it. A cycle of local
roots ends where it repeats.(local-roots deps-text)The :local/root paths in deps.edn (text, or nil), sorted: from :deps
and from every alias, since an alias not chosen today costs only a
cache miss if it is chosen later.
The `:local/root` paths in deps.edn (text, or nil), sorted: from `:deps` and from every alias, since an alias not chosen today costs only a cache miss if it is chosen later.
(parent-classpath-command {:keys [bb? aliases]})The command that prints the classpath the parent would start with now:
babashka's for the bb.edn in the current directory, or clojure -Spath
with the aliases of the JVM parent's basis.
The command that prints the classpath the parent would start with now: babashka's for the bb.edn in the current directory, or `clojure -Spath` with the `aliases` of the JVM parent's basis.
(parse-aliases s)A --aliases value such as :test:dev or test,dev as a vector of
keywords.
A `--aliases` value such as `:test:dev` or `test,dev` as a vector of keywords.
How many run times of each mode the history keeps.
How many run times of each mode the history keeps.
(record-history? mode cli-suites cli-options)Whether a complete run in mode goes into the history: a
heuristic-run? of the whole plan, with no suite (cli-suites) or
filter (cli-options) given on the command line.
Whether a complete run in `mode` goes into the history: a `heuristic-run?` of the whole plan, with no suite (`cli-suites`) or filter (`cli-options`) given on the command line.
(record-run history {:keys [in-process? wall-ms]})history after a run that ran every planned namespace, in process
(:in-process?) or not, in :wall-ms: the run's mode keeps its last
recent-runs times, newest last; the other mode keeps its own.
:workers-streak counts the short worker-process runs since the last
in-process one; a slow one leaves it as it was.
`history` after a run that ran every planned namespace, in process (`:in-process?`) or not, in `:wall-ms`: the run's mode keeps its last `recent-runs` times, newest last; the other mode keeps its own. `:workers-streak` counts the short worker-process runs since the last in-process one; a slow one leaves it as it was.
(refreshed-classpath fresh startup sep)The fresh classpath followed by the entries of the startup one it
lacks. Fresh entries come first so a changed dependency version wins;
the startup entries stay because they hold what the parent was started
with on top of the project file (a bb task's :extra-paths and
:extra-deps, volley itself).
The `fresh` classpath followed by the entries of the `startup` one it lacks. Fresh entries come first so a changed dependency version wins; the startup entries stay because they hold what the parent was started with on top of the project file (a bb task's `:extra-paths` and `:extra-deps`, volley itself).
(resolve-runtime requested bb-parent?)The worker runtime: an explicit requested (:bb or :jvm) wins,
otherwise workers use the runtime the parent runs on.
The worker runtime: an explicit `requested` (`:bb` or `:jvm`) wins, otherwise workers use the runtime the parent runs on.
How many short worker-process runs since the last in-process run make the next one try in process again, though the in-process runs on record were slow. A busy machine or a run that scaled out can make in-process runs look slow, and only another in-process run can show otherwise.
How many short worker-process runs since the last in-process run make the next one try in process again, though the in-process runs on record were slow. A busy machine or a run that scaled out can make in-process runs look slow, and only another in-process run can show otherwise.
(spath-command aliases)The command that prints the classpath for aliases.
The command that prints the classpath for `aliases`.
(split-classpath cp sep)Entries of a classpath string.
Entries of a classpath string.
(typical times)The median of times (the lower middle one of an even count), or nil
when there are none.
The median of `times` (the lower middle one of an even count), or nil when there are none.
(user-deps-file {:keys [clj-config xdg-config-home home]})The user-level deps.edn the Clojure CLI reads: $CLJ_CONFIG/deps.edn,
else $XDG_CONFIG_HOME/clojure/deps.edn, else ~/.clojure/deps.edn, as
in the clojure script. Blank values count as unset; nil without a
home.
The user-level deps.edn the Clojure CLI reads: `$CLJ_CONFIG/deps.edn`, else `$XDG_CONFIG_HOME/clojure/deps.edn`, else `~/.clojure/deps.edn`, as in the `clojure` script. Blank values count as unset; nil without a home.
(worker-plan {:keys [workers workers-set? in-process-ok? history]})How a run gets its workers: {:workers n :in-process? bool}.
:in-process? runs the tests on a thread of the parent JVM, starting
worker processes, up to :workers, only if the run outlasts
in-process-limit-ms. Input:
:workers the configured or default worker count:workers-set? true when --workers or tests.edn chose it: then
always that many worker processes:in-process-ok? whether this plan can run in process
(in-process-ok?):history record-run's map from earlier runsIn process when the recent in-process runs typically took at most
in-process-limit-ms. Otherwise the recent runs with worker processes
must typically have been that short, and then in process only when no
in-process run is on record, or after retry-after short
worker-process runs. Typically means the median of the last
recent-runs (the lower middle one of two), so one slow run on a busy
machine changes nothing. With no history, worker processes: a first
run (or CI) behaves as before.
How a run gets its workers: `{:workers n :in-process? bool}`.
`:in-process?` runs the tests on a thread of the parent JVM, starting
worker processes, up to `:workers`, only if the run outlasts
`in-process-limit-ms`. Input:
* `:workers` the configured or default worker count
* `:workers-set?` true when `--workers` or tests.edn chose it: then
always that many worker processes
* `:in-process-ok?` whether this plan can run in process
(`in-process-ok?`)
* `:history` `record-run`'s map from earlier runs
In process when the recent in-process runs typically took at most
`in-process-limit-ms`. Otherwise the recent runs with worker processes
must typically have been that short, and then in process only when no
in-process run is on record, or after `retry-after` short
worker-process runs. Typically means the median of the last
`recent-runs` (the lower middle one of two), so one slow run on a busy
machine changes nothing. With no history, worker processes: a first
run (or CI) behaves as before.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |