Concept: Parallel Scripts#

Overview#

Scripts run in parallel by default (disabled via --parallel=false in the CLI or parallel: false in the API), and you have control over how many concurrent scripts can run at the same time.

Parallel Max Value#

You can pass a number value, a percentage value (e.g. 50%), or one of the keywords "auto", "default", or "unbounded" to the parallel max option.

Value Types#

• A plain number sets the limit to the exact number of concurrent scripts. Setting the max to 2 then only allows two scripts to run at the same time.

• A value of "auto" sets the limit to os.availableParallelism(), which generally corresponds to the number of available logical CPUs. This is the default value when configuration doesn't override a default.

• A value of "unbounded" allows all scripts to run in parallel, but use this with caution, as it can overwhelm a machine and cause instability.

• A percentage value sets the limit to the percentage of os.availableParallelism(). Setting the max to 50% then sets the limit to roughly half of the available logical CPUs. Note that the limit is floored to the nearest integer above 0.

Default Limit#

A value of "default" explicitly references the default limit.

When the root config.defaults.parallelMax or environment variable BW_PARALLEL_MAX_DEFAULT is not set, it is equal to "auto". You can set config.defaults.parallelMax or BW_PARALLEL_MAX_DEFAULT to any of the valid values listed above.

Examples#

CLI:#

# Scripts run in parallel by default
# This is the same as passing --parallel=default
bw run my-script

# Normally "auto" or the value set by configuration 
# or environment variable (see Default Limit above)
bw run my-script --parallel=default

# Explicitly run in parallel, limiting the max 
# concurrent scripts to the available logical CPUs.
#
# This is the default unless the root config.defaults.parallelMax
# or process.env.BW_PARALLEL_MAX_DEFAULT is set to a different value.
bw run my-script --parallel=auto

# Run in series
bw run my-script --parallel=false

# Run in parallel with a max of the available logical CPUs
bw run my-script --parallel=auto

# Run in parallel with a max of 2 concurrent scripts
bw run my-script --parallel=2

# Run in parallel with a max of 50% of the available logical CPUs
bw run my-script --parallel=50%

# Run every script in parallel (use with caution)
bw run my-script --parallel=unbounded

API:#

import { createFileSystemProject } from "bun-workspaces";

const project = createFileSystemProject();

// Run in parallel with the default limit.
// Equal to "auto" or value of 
// the root config.defaults.parallelMax 
// or process.env.BW_PARALLEL_MAX_DEFAULT
project.runScriptAcrossWorkspaces({
  script: "my-script"
});

// Same result as above
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "default" },
});

// Run sequentially by disabling parallel
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: false,
});

// Run in parallel with the number of available logical CPUs
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "auto" },
});

// Run in parallel with a max of 2 concurrent scripts
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: 2 },
});

// Run in parallel with a max of 50% of the available logical CPUs
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "50%" },
});

// Run in parallel with no concurrency limit (use with caution)
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "unbounded" },
});