API Reference

Automatically borrow-check a function (best-effort).

BorrowChecker.@safe is a drop-in tripwire for existing code:

• Aliasing violations: mutating a value while another live binding may observe that mutation.
• Escapes / “moves”: storing a mutable value somewhere that outlives the current scope (e.g. a global cache / a field / a container), then continuing to reference it locally.

On function entry, it checks the current specialization and caches the result so future calls are fast. On failure it throws BorrowCheckError with best-effort source context.

Options

Options are parsed by the macro and compiled into a BorrowChecker.Config (and are part of the checked-cache key).

• scope (default: :function): controls whether the checker recursively borrow-checks callees (call-graph traversal).
  • :none: disable @safe entirely (no IR borrow-checking; returns the original definition).
  • :function: check only the annotated method.
  • :module: recursively check callees whose defining module matches the module where @safe is used.
  • :user: recursively check callees, but ignore Core and Base (including their submodules).
  • :all: recursively check callees across all modules (very aggressive).
• max_summary_depth (default: 12): limits recursive effect summarization depth used when the checker cannot directly resolve effects.
• debug (default: false): enable best-effort debug logging to a JSONL file (path controlled by BORROWCHECKER_AUTO_DEBUG_PATH).
• debug_callee_depth (default: 2): when debug=true, also dump IR for summary-recursion entries up to this depth (0 = only the entrypoint specialization).

Examples:

BorrowChecker.@safe scope=:module function f(x)
    g(x)
end

BorrowChecker.@safe max_summary_depth=4 optimize_until="compact 1" function h(x)
    g(x)
end

Extended help

optimize_until

optimize_until (default: BorrowChecker.DEFAULT_CONFIG.optimize_until) controls which compiler pass to stop at when fetching IR via Base.code_ircode_by_type.

Pass names vary across Julia versions; @safe tries to normalize common spellings like "compact 1" / "compact_1" when possible.

@unsafe begin
    ...
end

Mark a lexical region as unchecked by BorrowChecker.@safe.

Semantics (auto-IR checker only):

• The borrow checker does not validate aliasing / uniqueness rules for statements inside the @unsafe region.
• The borrow checker does not enforce escape/consume ("move") rules inside the @unsafe region.
• The unsafe region is treated as opaque to surrounding checked code: effects inside the region (writes, consumes, escapes, new aliases) are not propagated outward into the surrounding analysis.
• The checker does not recursively borrow-check callees that are only reachable from within the @unsafe region.
• The unsafe region is still executed normally at runtime and evaluates to the value of its last expression (like a begin ... end block).

This is intentionally analogous to @inbounds: it is an escape hatch for low-level code or for cases where the checker is overly conservative. The responsibility to uphold the usual invariants is on you.

BorrowCheckError <: Exception

Thrown by BorrowChecker.@safe when a method specialization violates borrow-checking rules. Carries the checked signature (tt) and the list of individual BorrowViolations; showerror renders a source-level diagnostic for each violation.

disable_by_default!(m::Module)

Make all BorrowChecker macros expand to pass-through within module m unless a LocalPreferences.toml explicitly sets borrow_checker = true. Intended for libraries that ship with checking disabled and enable it in their test suite. Must be called before any BorrowChecker macro is used in m.