Home • Explore • Blog • CI
☰



rustc
1st chunk of `src/profile-guided-optimization.md`
dcd35c2fe25367de344e435c9427333cd2059cef9cbfb3150000000100000a41
# Profile Guided Optimization

<!-- toc -->

`rustc` supports doing profile-guided optimization (PGO).
This chapter describes what PGO is and how the support for it is
implemented in `rustc`.

## What Is Profiled-Guided Optimization?

The basic concept of PGO is to collect data about the typical execution of
a program (e.g. which branches it is likely to take) and then use this data
to inform optimizations such as inlining, machine-code layout,
register allocation, etc.

There are different ways of collecting data about a program's execution.
One is to run the program inside a profiler (such as `perf`) and another
is to create an instrumented binary, that is, a binary that has data
collection built into it, and run that.
The latter usually provides more accurate data.

## How is PGO implemented in `rustc`?

`rustc` current PGO implementation relies entirely on LLVM.
LLVM actually [supports multiple forms][clang-pgo] of PGO:


- Sampling-based PGO where an external profiling tool like `perf` is used
  to collect data about a program's execution.
- GCOV-based profiling, where code coverage infrastructure is used to collect
  profiling information.
- Front-end based instrumentation, where the compiler front-end (e.g. Clang)
  inserts instrumentation intrinsics into the LLVM IR it generates (but see the
  [^note-instrument-coverage]"Note").
- IR-level instrumentation, where LLVM inserts the instrumentation intrinsics
  itself during optimization passes.

`rustc` supports only the last approach, IR-level instrumentation, mainly
because it is almost exclusively implemented in LLVM and needs little
maintenance on the Rust side. Fortunately, it is also the most modern approach,
yielding the best results.

So, we are dealing with an instrumentation-based approach, i.e. profiling data
is generated by a specially instrumented version of the program that's being
optimized. Instrumentation-based PGO has two components: a compile-time
component and run-time component, and one needs to understand the overall
workflow to see how they interact.

instrumentation, via the experimental option
[`-C instrument-coverage`](./llvm-coverage-instrumentation.md), but using these
coverage results for PGO has not been attempted at this time.

### Overall Workflow

Generating a PGO-optimized program involves the following four steps:

1. Compile the program with instrumentation enabled (e.g. `rustc -C profile-generate main.rs`)
2. Run the instrumented program (e.g. `./main`) which generates a `default-<id>.profraw` file
3. Convert the `.profraw` file into a `.profdata` file using LLVM's `llvm-profdata` tool.
Title: Profile Guided Optimization in `rustc`
Summary
This section discusses Profile-Guided Optimization (PGO) in `rustc`. PGO involves collecting data about a program's typical execution to optimize aspects like inlining and machine-code layout. `rustc`'s PGO relies on LLVM's IR-level instrumentation, which is a modern approach that yields the best results. The process involves compiling with instrumentation enabled, running the instrumented program to generate a `.profraw` file, and converting it to a `.profdata` file using LLVM's `llvm-profdata` tool.