PrecompileTools

https://julialang.github.io/PrecompileTools.jl/stable/
Admin
PrecompileTools is a Julia package designed to reduce the delay on first usage of Julia code by...
Tokens:4,634
Snippets:51
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Precompile Workload with Setup

Source: https://julialang.github.io/PrecompileTools.jl/stable

Use `@setup_workload` for items that can reduce precompile file size and `@compile_workload` for calls to be precompiled. Ensure `@compile_workload` is at the top level, not inside functions.

```julia
module MyPackage

using PrecompileTools: @setup_workload, @compile_workload    # this is a small dependency

struct MyType
    x::Int
end
struct OtherType
    str::String
end

@setup_workload begin
    # Putting some things in `@setup_workload` instead of `@compile_workload` can reduce the size of the
    # precompile file and potentially make loading faster.
    list = [OtherType("hello"), OtherType("world!")]
    @compile_workload begin
        # all calls in this block will be precompiled, regardless of whether
        # they belong to your package or not (on Julia 1.8 and higher)
        d = Dict(MyType(1) => list)
        x = get(d, MyType(2), nothing)
        last(d[MyType(1)])
    end
end

end

```

--------------------------------

### Configure Startup Package for Precompilation

Source: https://julialang.github.io/PrecompileTools.jl/stable

Defines the 'Startup' module, imports necessary packages, and uses the '@compile_workload' macro to specify code that should be precompiled. This is where you place a toy example of your workload.

```julia
module Startup

using LotsOfPackages...
using PrecompileTools

@compile_workload begin
    # inside here, put a "toy example" of everything you want to be fast
end

end
```

--------------------------------

### Setup Workload for Precompilation

Source: https://julialang.github.io/PrecompileTools.jl/stable/reference

Use `@setup_workload` to run code only during package precompilation. It is often used in conjunction with `@compile_workload` to prepare variables and then precompile functions using those variables.

```julia
@setup_workload begin
    vars = ...
    ⋮
end
```

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

--------------------------------

### Setup Data for Precompilation with @setup_workload

Source: https://julialang.github.io/PrecompileTools.jl/stable/explanations

Use the `@setup_workload` macro to create data structures that can be utilized within a `@compile_workload` block. This code also runs only during precompilation but its output is not necessarily stored in the precompile file.

```julia
@setup_workload begin
    # Code to set up data for precompilation
end
```

--------------------------------

### Develop Startup Package and Add Dependencies

Source: https://julialang.github.io/PrecompileTools.jl/stable

This snippet shows how to develop the 'Startup' package and add 'PrecompileTools' along with other required packages. These dependencies will be precompiled.

```julia
(Project1) pkg> dev ./Startup
   Resolving package versions...
    Updating `/tmp/Project1/Project.toml`
  [e9c42744] + Startup v0.1.0 `Startup`
    Updating `/tmp/Project1/Manifest.toml`
  [e9c42744] + Startup v0.1.0 `Startup`

(Project1) pkg> activate Startup/
  Activating project at `/tmp/Project1/Startup`

(Startup) pkg> add PrecompileTools LotsOfPackages...
```

--------------------------------

### Activate Project and Generate Startup Package

Source: https://julialang.github.io/PrecompileTools.jl/stable

Steps to activate a local project and generate a new 'Startup' package within it. This sets up the basic structure for custom precompilation.

```julia
(@v1.9) pkg> activate .
  Activating new project at `/tmp/Project1`

(Project1) pkg> generate Startup
  Generating  project Startup:
    Startup/Project.toml
    Startup/src/Startup.jl
```

--------------------------------

### PrecompileTools.@setup_workload

Source: https://julialang.github.io/PrecompileTools.jl/stable/reference

`@setup_workload` runs the code block only during package precompilation. It is often used in combination with `@compile_workload` to set up necessary variables or states before precompilation tasks.

```APIDOC
## Macro: @setup_workload

### Description
Executes the code block exclusively during the package precompilation phase. This macro is commonly paired with `@compile_workload` to prepare the environment or define variables needed for the precompilation process.

### Syntax
```julia
@setup_workload begin
    vars = ...
    ⋮
end
```

### Usage Example
```julia
@setup_workload begin
    vars = ...
    @compile_workload begin
        y = f(vars...)
        g(y)
        ⋮
    end
end
```

### Note
`@setup_workload` does not force compilation itself, although compilation might occur incidentally. It also does not intentionally capture runtime dispatches, though they will be precompiled if they belong to your package.
```

--------------------------------

### View Precompiled Calls in Julia

Source: https://julialang.github.io/PrecompileTools.jl/stable

Enable verbose mode to see a list of method instances that will be precompiled. This shows direct- or runtime-dispatched instances, omitting inferrable callees. Ensure you are in the package directory and include the main package file.

```julia
using PrecompileTools

PrecompileTools.verbose[] = true   # runs the block even if you're not precompiling, and print precompiled calls

include("src/MyPackage.jl");
```

--------------------------------

### Wrap Package Imports with @recompile_invalidations

Source: https://julialang.github.io/PrecompileTools.jl/stable

Use this snippet in a "Startup" package to wrap `using` statements for multiple packages. This ensures that any code invalidations triggered during package loading are recompiled.

```julia
module Startup

using PrecompileTools
@recompile_invalidations begin
    using LotsOfPackages...
end

# Maybe a @compile_workload here?

end
```

--------------------------------

### Precompile Specific Signatures in Julia

Source: https://julialang.github.io/PrecompileTools.jl/stable/explanations

Use Julia's built-in `precompile` function to force precompilation of specific method signatures and their inferrable callees.

```julia
precompile(foo, (ArgType1, ArgType2))
```

--------------------------------

### Define a simple function method

Source: https://julialang.github.io/PrecompileTools.jl/stable/invalidations

This is the initial definition of a function with a single method. It serves as the baseline for demonstrating code invalidation.

```julia
numchildren(::Any) = 1
```

--------------------------------

### Precompile Code Without Execution

Source: https://julialang.github.io/PrecompileTools.jl/stable

Use Julia's `precompile` function when direct execution of a workload is not possible, such as when connecting to a database or on a headless server. Analysis with SnoopCompile may be required to generate optimal `precompile` directives.

```julia
let
    # workload goes here
end
```

--------------------------------

### Define Precompilation Workload

Source: https://julialang.github.io/PrecompileTools.jl/stable/reference

Use `@compile_workload` to precompile all method calls within the expression. This ensures that all direct and indirect callees are cached during package precompilation.

```julia
@compile_workload f(args...)
```

--------------------------------

### Fully Disable PrecompileTools.jl

Source: https://julialang.github.io/PrecompileTools.jl/stable

Completely disable PrecompileTools.jl for all packages by setting the 'precompile_workloads' preference to false. This can help reduce system image size when using PackageCompiler.jl.

```julia
using PrecompileTools, Preferences
set_preferences!(PrecompileTools, "precompile_workloads" => false; force=true)
```

--------------------------------

### PrecompileTools.@compile_workload

Source: https://julialang.github.io/PrecompileTools.jl/stable/reference

`@compile_workload` precompiles (and saves in the `compile_workload` file) any method calls that occur inside the expression. All calls (direct or indirect) inside a `@compile_workload` block will be cached. This macro ensures code runs only during package precompilation, disables the interpreter, and precompiles both direct and indirect callees.

```APIDOC
## Macro: @compile_workload

### Description
Precompiles method calls within the given expression, saving them to a `compile_workload` file. This ensures that all direct and indirect calls within the block are cached and compiled during package precompilation.

### Syntax
```julia
@compile_workload f(args...)
```

### Features
1. Code inside runs only when the package is being precompiled.
2. The interpreter is disabled, ensuring calls are compiled.
3. Both direct and indirect callees will be precompiled, even for methods defined in other packages and for runtime-dispatched callees (requires Julia 1.8+).

### Note
For comprehensive precompilation, ensure the first usage of a given method/argument-type combination occurs inside `@compile_workload`. This is particularly important for direct calls to methods defined in Base or other packages, or indirect runtime-dispatched calls to such methods.
```

--------------------------------

### Wrap Method Extensions with @recompile_invalidations

Source: https://julialang.github.io/PrecompileTools.jl/stable

As a package developer, wrap method definitions that extend functions from Base or other packages. This helps prevent "collateral damage" and improves the user's out-of-the-box experience, but may increase precompilation time.

```julia
module MyContainers

using AnotherPackage
using PrecompileTools

struct Container
    list::Vector{Any}
end

# This is a function created by this package, so it doesn't need to be wrapped
make_container() = Container([])

@recompile_invalidations begin
    # Only those methods extending Base or other packages need to go here
    Base.push!(obj::Container, x) = ...
    function AnotherPackage.foo(obj::Container)
        ⋮
    end
end

end
```

--------------------------------

### Execute Code During Precompilation with @compile_workload

Source: https://julialang.github.io/PrecompileTools.jl/stable/explanations

The `@compile_workload` macro ensures that statements within it are executed only during package precompilation. It caches non-inferrable callees made via runtime dispatch, regardless of module ownership, and disables the interpreter within the block to guarantee compilation.

```julia
@compile_workload begin
    # Code to be executed during precompilation
end
```

--------------------------------

### Log and Recompile Invalidations with @recompile_invalidations

Source: https://julialang.github.io/PrecompileTools.jl/stable/explanations

The `@recompile_invalidations` macro activates logging of invalidations, parses the log to identify top-level calls, and triggers their recompilation. Be aware that recompiled code might produce different results.

```julia
@recompile_invalidations begin
    # Code block to monitor for invalidations
end
```

--------------------------------

### Add a second method to an existing function

Source: https://julialang.github.io/PrecompileTools.jl/stable/invalidations

Adding a new method to `numchildren` after `total_children` has been defined. This scenario triggers code invalidation for `total_children` to ensure consistent compilation.

```julia
numchildren(::BinaryNode) = 2
```

--------------------------------

### Disable Precompile Workloads Locally for a Package

Source: https://julialang.github.io/PrecompileTools.jl/stable

Package developers can temporarily disable precompile workloads for a specific package during development using Preferences.jl. This avoids the cost of precompilation while actively modifying the package.

```julia
using MyPackage, Preferences
set_preferences!(MyPackage, "precompile_workload" => false; force=true)
```

```julia
[MyPackage]
precompile_workload = false
```

--------------------------------

### Define a function that uses another function

Source: https://julialang.github.io/PrecompileTools.jl/stable/invalidations

This function utilizes the previously defined `numchildren` function. Its compilation can be affected by changes to `numchildren`'s methods.

```julia
total_children(list) = sum(numchildren.(list))
```

--------------------------------

### PrecompileTools.@recompile_invalidations

Source: https://julialang.github.io/PrecompileTools.jl/stable/reference

`@recompile_invalidations` recompiles any invalidations that occur within the given expression. This macro is generally intended for users creating "Startup" packages to ensure that code compiled by package authors is not invalidated.

```APIDOC
## Macro: @recompile_invalidations

### Description
Recompiles any invalidations that occur within the provided code block. This is typically used in "Startup" packages to maintain the integrity of precompiled code from other packages.

### Syntax
```julia
@recompile_invalidations begin
    using PkgA
    ⋮
end
```
```

--------------------------------

### Handle Recompilation Invalidations

Source: https://julialang.github.io/PrecompileTools.jl/stable/reference

Use `@recompile_invalidations` to recompile any invalidations that occur within the given expression. This is useful for startup packages to prevent code compiled by package authors from being invalidated.

```julia
@recompile_invalidations begin
    using PkgA
    ⋮
end
```
Tokens:
Raw