Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The [[likely]] attribute is a C++20 standard attribute specifier that provides an explicit static hint to the compiler’s optimizer indicating that a specific execution path is highly probable. By annotating a statement or label, developers instruct the compiler to prioritize that branch during code generation, typically optimizing for instruction cache locality, basic block placement, and static branch prediction heuristics.

​
Syntax and Placement

The attribute appertains to the statement or label it immediately precedes. It is evaluated during the compiler’s control-flow graph (CFG) construction phase. Branch Statements: When dealing with conditional branching, the attribute is typically applied to the statement representing the true or false branch, rather than the if statement itself. To mark the true branch as likely, apply the attribute to the true-branch statement: 
if (condition) [[likely]] {
    // Appertains to this compound statement (the true branch)
} else {
    // ...
}
To mark the false branch as likely, apply the attribute to the false-branch statement: 
if (condition) {
    // ...
} else [[likely]] {
    // Appertains to this compound statement (the false branch)
}
Applying the attribute to the if statement itself is syntactically valid but semantically different. It indicates that the control flow reaching the if statement is likely, rather than prioritizing a specific branch: 
[[likely]] if (condition) {
    // Appertains to the entire 'if' statement
}
Switch Labels: Within a switch block, the attribute appertains to a specific case or default label, indicating that the control flow is highly likely to jump to that specific label. It does not appertain to the switch statement itself. 
switch (evaluation) {
    case 0:
        // ...
        break;
    [[likely]] case 1:
        // Appertains to the 'case 1' label
        break;
    case 2:
        // ...
        break;
}
Iteration Statements: The attribute can be applied to the body of a loop to indicate that the loop will likely iterate multiple times, or to a jump statement (break, continue, return) to indicate early termination is likely. 
while (condition) [[likely]] {
    // Appertains to the loop body statement
}

​
Compiler Mechanics

The [[likely]] attribute does not alter the observable semantics, logic, or correctness of the C++ program. Instead, it influences the backend optimization passes in the following ways:
  1. Basic Block Layout: The compiler reorganizes the generated assembly so that the basic block of the [[likely]] path is placed contiguously in memory with the preceding instructions. This prevents a jump instruction from being executed on the hot path, maximizing instruction cache (i-cache) hits and prefetching efficiency.
  2. Out-of-line Cold Paths: Conversely, alternative paths (the implicit “unlikely” branches) are often moved out-of-line to the end of the function or a separate text section, reducing i-cache pollution.
  3. Inlining Heuristics: The optimizer may increase the aggressiveness of function inlining for calls made within a [[likely]] block, while suppressing inlining for alternative paths to reduce code bloat on the hot path.
  4. Register Allocation: Variables used exclusively in the likely path may be prioritized for allocation in CPU registers rather than being spilled to the stack.

​
Constraints and Rules

  • Mutually Exclusive: A single statement or label cannot be annotated with both [[likely]] and [[unlikely]].
  • Scope: The attribute applies strictly to the statement or label it precedes. It cannot be applied to declarations.
  • Non-binding: The attribute’s effect on the generated machine code is non-deterministic. The compiler is permitted to ignore the attribute entirely if its internal cost models determine that the hint degrades performance, or if the target architecture does not benefit from static branch hints.
Master C++ with Deep Grasping Methodology!Learn More