> ## 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.
# C++ Unlikely Attribute
The `[[unlikely]]` attribute is a C++20 standard optimization hint that informs the compiler that a specific execution path is statistically improbable. By applying this attribute to a statement or label, developers instruct the compiler's backend to de-prioritize the associated branch during instruction scheduling, basic block placement, and static branch prediction.
## Compiler Behavior
When a compiler encounters `[[unlikely]]`, it typically alters the generated machine code in the following ways:
* **Basic Block Placement:** The compiler moves the "cold" (unlikely) basic blocks out of the primary linear execution path. This improves instruction cache (i-cache) locality for the "hot" path by preventing the CPU from fetching instructions that will rarely be executed.
* **Branch Prediction:** The compiler may emit specific branch prediction prefixes (depending on the target architecture) or structure conditional jumps such that the fall-through path aligns with the likely execution flow.
## Syntax and Placement
The attribute appertains to the statement or label it immediately precedes. It is most commonly applied to conditional branches (`if` statements) and `switch` cases.
**Conditional Statements:**
When applied to an `if` or `else` branch, the attribute must precede the statement block.
```cpp theme={"dark"}
if (condition) [[unlikely]] {
// Compiler assumes this block is rarely executed
execute_cold_path();
} else {
// Compiler assumes this is the dominant path
execute_hot_path();
}
```
It can also be applied to the `else` branch directly:
```cpp theme={"dark"}
if (condition) {
execute_hot_path();
} else [[unlikely]] {
execute_cold_path();
}
```
**Switch Statements:**
In a `switch` block, the attribute appertains to the `case` or `default` label.
```cpp theme={"dark"}
switch (value) {
case 1:
process_standard();
break;
[[unlikely]] case 2:
process_anomaly();
break;
default:
process_default();
break;
}
```
**Iteration Statements:**
It can be applied to loop bodies to indicate that the loop will rarely execute or will terminate quickly.
```cpp theme={"dark"}
while (condition) [[unlikely]] {
process_rare_event();
}
```
## Technical Constraints
* **Non-binding Hint:** The attribute is strictly a heuristic hint. The C++ standard does not mandate any specific optimization, and compilers are permitted to ignore it entirely, especially if Profile-Guided Optimization (PGO) data contradicts the attribute.
* **Mutually Exclusive:** A single statement or label cannot be marked with both `[[likely]]` and `[[unlikely]]`.
* **Statement-Level Only:** The attribute applies to statements and labels, not to expressions or declarations. Applying it to a boolean expression directly (e.g., `if ([[unlikely]] x > 5)`) is syntactically invalid.
Tired of Poor C++ Skills? Fix That With Deep Grasping!
Learn More
