DispatchDoctor.jl

The @stable macro can be applied to large scopes. It will recursively apply to:

• Code inside begin...end blocks
• module definitions
• Included files via include()
• Nested submodules

All methods defined within these scopes will be wrapped with the type stability check.

@stable begin
    f() = rand(Bool) ? 0 : 1.0
    
    module A
        g(; a, b) = a + b
        include("myfile.jl")

        module B
            using DispatchDoctor: @unstable
            @unstable h() = rand(Bool) ? 0 : 1.0
        end
    end
end

DispatchDoctor automatically skips stability checks in the following cases:

• During precompilation.
• In unsupported Julia versions (currently only 1.10.0 and 1.13.0 are active).
• When loading code changes via Revise.jl.
• Within @unstable blocks.
• Within @generated blocks.
• Within functions containing @nospecialize.
• Within quote ... end or macro ... end blocks.
• Within incompatible macros (e.g., @eval, @assume_effects, @pure).
• For parameterized functions (e.g., MyType{T}(args...)).
• For functions with expression-based names (e.g., (::MyType)(args...)).
• For closures (the closure itself is not stabilized, but the outer function is).

The @stable macro accepts several configuration options to control behavior:

• default_mode::String="error": Sets the reaction to instability. Options are "error" (default), "warn" (emit warning only), or "disable" (no effect).
• default_codegen_level::String="debug": Controls code generation. "debug" (default) generates a duplicate function for use with @code_warntype. "min" generates only a single function body to improve precompilation time.
• default_union_limit::Int=1: The maximum number of elements in a Union to be considered stable. A value of 1 means all Union types are unstable. A value of 2 allows Union{Float32, Float64} to be considered stable.

If @stable throws a TypeInstabilityError, use these tools to locate the source:

1. @code_warntype: Built into Julia; highlights unstable variables in color.
2. Cthulhu.jl: Provides detailed type instability reports.
3. JET.jl: Provides advanced analysis and can descend into function calls to find the source of instability.

You can opt-out of type stability checks in two ways:

1. @unstable macro: Inverts the effect of @stable. Use this inside an @stable block to exempt specific functions or code blocks.
2. allow_unstable() context: Disables stability errors for a specific scope. Note that this cannot be used simultaneously from two separate threads.

@stable f(x) = x > 0 ? x : 0.0

allow_unstable() do
           f(1)
       end

@stable begin
    @unstable h() = rand(Bool) ? 0 : 1.0
    @unstable begin
        h(x::Int) = rand(Bool) ? 0 : 1.0
    end
end

DispatchDoctor provides two primary macros to manage stability annotations in your code:

• @stable: Marks a function or code block as stable. When used, @stable propagates macros to both the function definition and the function simulator.
• @unstable: Inverts the behavior of @stable. Use this to mark code as unstable or to override a stable context.

The @stable macro is used to ensure that functions return concrete types. If a function call results in a non-concrete type (like a Union), DispatchDoctor will throw a TypeInstabilityError.

When code is type-stable, the check is designed to compile away, resulting in zero runtime overhead in many cases.

using DispatchDoctor: @stable

@stable function relu(x)
    if x > 0
        return x
    else
        return 0.0
    end
end

If you have a function marked as @stable but need to call a specific function within that context without the stability constraints, use the allow_unstable utility.

# Example usage pattern
allow_unstable(unstable_function, args...)