magus v0.4.2 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

Race condition diagnostics

Codes in the MGS4xxx range are emitted by the magus race condition detector. Enable with magus run <target> --race.

The --race flag follows the --output pattern: an enumerated mode value. Modes are orthogonal and can be combined with a comma:

magus run build                          # no race diagnostics
magus run build --race=watch             # cheap: fsnotify + static checks
magus run build --race=replay            # determinism only
magus run build --race=watch,replay      # everything
Mode Codes emitted Cost
(omitted) MGS4002 only free (static check, always on)
watch MGS4001, MGS4002, MGS4004 near-zero (fsnotify)
replay MGS4002, MGS4003 roughly doubles wall-clock
watch,replay all four watch overhead + 2× wall-clock

MGS4002 (declared-output overlap) is always emitted: a static check at graph construction time, with zero runtime cost, no flag required.

watch is safe to leave on for every CI run. replay re-executes the affected set sequentially with the cache bypassed, so reserve it for a scheduled audit or a manual audit rather than every push.

Codes

  • MGS4001: filesystem race condition.
  • MGS4002: declared output overlap.
  • MGS4003: non-deterministic output.
  • MGS4004: potential undeclared dependency.
  • MGS4007: undeclared source modified. Always on, like MGS4002, and needs no --race: the comparison is between two hashes of the declared source set, which every run computes anyway.
racediagnosticserror codesMGS4xxxconcurrencydeterminismwatchreplay
Last updated (9edeede5)
Earlier changes on this page (2)

Full history ↗ · Blame source ↗

Glossary

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Concurrency

How many targets run at once. It is bounded by the pool's capacity and set with --concurrency, MAGUS_CONCURRENCY, or the concurrency config key. See daemon.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.