BackgroundScripts

Background Script Execution

Outset 4.3 adds support for running scripts concurrently in the background while other scripts continue to run sequentially in the foreground.

How it works

Scripts are classified as background or foreground based on their filename:

• Background scripts have a filename that starts with an underscore (_), e.g. _my-task.sh
• Foreground scripts follow the normal naming convention, e.g. 10_configure.sh

When Outset processes a directory that contains background scripts:

1. All background scripts are dispatched concurrently on background threads immediately.
2. Foreground scripts then run sequentially on the main thread, in alphanumeric order, as normal.
3. Outset waits for all background scripts to finish before it exits.

This means a slow background script will not delay foreground scripts, and foreground scripts will not delay the start of background scripts.

Naming and ordering

Alphanumeric ordering still applies within each group. If you have multiple background scripts and need them to run in a specific order, that is not supported — background scripts always run concurrently with each other. Use foreground scripts if sequential ordering is required.

Background and foreground scripts can coexist in the same directory:

/usr/local/outset/login-every/
    10_configure-dock.sh        ← foreground, runs first
    20_configure-finder.sh      ← foreground, runs second
    _sync-preferences.sh        ← background, runs concurrently with foreground scripts
    _cache-assets.sh            ← background, runs concurrently with foreground scripts

Run-once semantics

Background scripts placed in a *-once directory behave correctly:

• Outset checks the run-once record before dispatching the script.
• If the script has already run successfully, it is skipped.
• On successful completion, the run-once record is written.

Logging

All log output from background scripts is tagged with the child process identifier to make it easy to distinguish background output from foreground output when reading the log:

[BG:pid=12345] _sync-preferences.sh: starting sync
10_configure-dock.sh: configuring dock
[BG:pid=12346] _cache-assets.sh: caching assets
[BG:pid=12345] _sync-preferences.sh: sync complete
20_configure-finder.sh: configuring Finder

Script output is streamed to the log in real time as each line is produced, so background and foreground log lines will interleave naturally.

See Logging for details on how to view Outset's log output.

Timeout

By default, Outset waits indefinitely for background scripts to finish. If a background script hangs, Outset will not exit until it is terminated externally.

To set a global timeout (in seconds) for background scripts, set the background_script_timeout preference key:

<key>background_script_timeout</key>
<integer>300</integer>

When a timeout is configured:

• Each background script is given that many seconds to complete.
• If a script exceeds the timeout it is terminated and an error is logged.
• Outset waits up to background_script_timeout + 5 seconds for all background tasks to conclude before continuing.

See Preferences for details on how to manage preference keys.

Supported directories

Background script execution is supported in all script directories:

• boot-once / boot-every
• login-once / login-every
• login-privileged-once / login-privileged-every
• login-window
• on-demand