GitHub

Reference (API)

API documentation for PrecompileTools.

PrecompileTools.check_edges — Method
check_edges(node)

Recursively ensure that all callees of node are precompiled. This is (rarely) necessary because sometimes there is no backedge from callee to caller (xref https://github.com/JuliaLang/julia/issues/49617), and staticdata.c relies on the backedge to trace back to a MethodInstance that is tagged mi.precompiled.

source
PrecompileTools.@compile_workload — Macro
@compile_workload f(args...)

precompile (and save in the compileworkload file) any method-calls that occur inside the expression. All calls (direct or indirect) inside a `@compileworkload` block will be cached.

@compile_workload has three key features:

  1. code inside runs only when the package is being precompiled (i.e., a *.ji precompile compile_workload file is being written)
  2. the interpreter is disabled, ensuring your calls will be compiled
  3. both direct and indirect callees will be precompiled, even for methods defined in other packages and even for runtime-dispatched callees (requires Julia 1.8 and above).
Note

For comprehensive precompilation, ensure the first usage of a given method/argument-type combination occurs inside @compile_workload.

In detail: runtime-dispatched callees are captured only when type-inference is executed, and they are inferred only on first usage. Inferrable calls that trace back to a method defined in your package, and their inferrable callees, will be precompiled regardless of "ownership" of the callees (Julia 1.8 and higher).

Consequently, this recommendation matters only for:

- direct calls to methods defined in Base or other packages OR
- indirect runtime-dispatched calls to such methods.
source
PrecompileTools.@recompile_invalidations — Macro
@recompile_invalidations begin
    using PkgA
    ⋮
end

Recompile any invalidations that occur within the given expression. This is generally intended to be used by users in creating "Startup" packages to ensure that the code compiled by package authors is not invalidated.

source
PrecompileTools.@setup_workload — Macro
@setup_workload begin
    vars = ...
    ⋮
end

Run the code block only during package precompilation. @setup_workload is often used in combination with @compile_workload, for example:

@setup_workload begin
    vars = ...
    @compile_workload begin
        y = f(vars...)
        g(y)
        ⋮
    end
end

@setup_workload does not force compilation (though it may happen anyway) nor intentionally capture runtime dispatches (though they will be precompiled anyway if the runtime-callee is for a method belonging to your package).

source