likely and unlikely Macros in C: How Branch Prediction Hints Work

By the end of this page, you will understand what likely() and unlikely() mean in C, how they use __builtin_expect() to give the compiler branch prediction hints, and why that can affect generated machine code. You will also learn when these hints are useful, when they are unnecessary, and how real projects use them carefully rather than everywhere.

likely() and unlikely() are macros used to tell the compiler which outcome of a condition is expected to happen most of the time.

In GCC- and Clang-style C code, they usually wrap __builtin_expect():

#define likely(x)   __builtin_expect(!!(x), 1)
#define unlikely(x) __builtin_expect(!!(x), 0)

Here is the key idea:

• likely(x) means: "this expression is usually true"
• unlikely(x) means: "this expression is usually false"

What __builtin_expect() does

__builtin_expect(actual_value, expected_value) returns actual_value, but also gives the compiler a hint about which value is more probable.

So this:

if (unlikely(fd < 0))

becomes a hint saying:

• the expression fd < 0 is usually false
• the error path is rare

Likewise:

Think of a branch like a hallway with two doors:

• one door is used 99% of the time
• the other door is only for emergencies

likely() and unlikely() are like putting a sign on the hallway for the architect:

• "Most people go through this door"
• "The emergency door is rarely used"

The sign does not force anyone to choose a door. Instead, it helps the architect design the building so the normal route is smooth and direct, while the rare route can be off to the side.

That is what the compiler does with these macros: it tries to make the common path cheaper and keep uncommon paths out of the way.

The common Linux-style definitions are:

#define likely(x)   __builtin_expect(!!(x), 1)
#define unlikely(x) __builtin_expect(!!(x), 0)

Basic syntax

if (likely(count > 0)) {
    process_items();
} else {
    handle_empty_case();
}

This tells the compiler that count > 0 is usually true.

Example: rare error path

#include <stdio.h>

#define likely(x)   __builtin_expect(!!(x), 1)
#define unlikely(x) __builtin_expect(!!(x), 0)

int divide(int a, int b) {
    if (unlikely(b == 0)) {
        return 0;  // error case
    }

    return a / b;
}

int main(void) {
    printf("%d\n", divide(, ));
     ;
}

Consider this example:

#include <stdio.h>

#define likely(x)   __builtin_expect(!!(x), 1)
#define unlikely(x) __builtin_expect(!!(x), 0)

int read_value(int ok) {
    if (unlikely(!ok)) {
        return -1;
    }

    return 42;
}

Step-by-step for read_value(1)

1. ok is 1
2. !ok becomes 0
3. !!(!ok) is still 0
4. __builtin_expect(0, 0) returns 0
5. The if condition is false
6. The function returns 42

Step-by-step for read_value(0)

likely() and unlikely() are most useful in places where one branch is strongly dominant.

Common real scenarios

Error handling in hot code

if (unlikely(ptr == NULL)) {
    return ERROR;
}

In many systems, failure is rare, so the normal path should stay fast.

Fast-path vs slow-path logic

if (likely(cache_hit)) {
    return cached_value;
}
return recompute_value();

If cache hits are common, it makes sense to optimize that path.

Kernel and systems programming

Operating systems, device drivers, schedulers, and memory allocators often have:

• very hot code paths
• tight loops
• rare exceptional conditions

This is where branch hints are more likely to matter.

Network packet processing

if (unlikely(packet == NULL)) {
    drop_packet();
}

When millions of packets are processed, even small layout improvements can matter.

Input validation with rare failure

In real projects, developers usually do not wrap every if with likely() or unlikely().

They apply these hints selectively.

Common patterns

Guard clauses for rare failures

int process(struct item *item) {
    if (unlikely(item == NULL)) {
        return -1;
    }

    if (unlikely(item->data == NULL)) {
        return -2;
    }

    return do_work(item);
}

This keeps the common valid path clean.

Fast path / slow path separation

if (likely(state == READY)) {
    run_fast_path();
} else {
    run_slow_path();
}

Validation in performance-sensitive functions

if (unlikely(size > limit)) {
    log_error();
    return 0;
}

Error handling macros and helpers

1. Thinking they change logic

These macros do not change what the program does.

Broken assumption:

if (unlikely(x > 0)) {
    // some developers think this is treated differently logically
}

Reality:

• the condition is still evaluated normally
• true is still true, false is still false
• only optimization metadata changes

2. Using them everywhere

Overusing branch hints can make code noisy and harder to read.

Poor style:

if (likely(a > b)) {
    ...
}
if (likely(i < n)) {
    ...
}
if (unlikely(flag)) {
    ...
}

If every branch is annotated, the hints lose meaning and readability suffers.

3. Guessing the wrong branch probability

If you mark the uncommon path as likely, you can hurt performance.

if (likely(error_occurred)) {
    handle_error();
}

If errors are actually rare, this hint is misleading.

4. Ignoring portability

__builtin_expect() is compiler-specific.

Safer pattern:

likely/unlikely vs plain if

#define likely(x)   __builtin_expect(!!(x), 1)
#define unlikely(x) __builtin_expect(!!(x), 0)

Quick rules

• likely(x): x is usually true
• unlikely(x): x is usually false
• they do not change correctness
• they are compiler hints, not guarantees
• they are most useful in hot code with strongly biased branches

Why !!(x)?

• converts any nonzero value to 1
• converts zero to 0

Best uses

• rare error handling
• hot fast-path code
• low-level systems code
• branches confirmed by profiling

Avoid when

• code is not performance-sensitive
• branch probabilities are unclear
• readability would get worse
• you expect big gains without measuring

Portable fallback

#if defined(__GNUC__) || defined(__clang__)

What do likely() and unlikely() do in C?

They wrap __builtin_expect() to tell the compiler which branch is expected to happen most often.

Do likely() and unlikely() make code faster?

Sometimes, but usually only by a small amount. They help most in hot code where one branch is clearly much more common than the other.

Do these macros affect program correctness?

No. They do not change the meaning of the condition. They only provide optimization hints.

Why does the Linux kernel use them so much?

The kernel contains performance-sensitive low-level code where error paths are often rare and fast paths are very important.

Should I use likely() and unlikely() in user-space code?

Only if the code is performance-critical and profiling or domain knowledge shows a strong branch bias. Otherwise, plain if is usually better.

Are likely() and unlikely() portable?

Not fully. They rely on compiler support for __builtin_expect(). Many projects add fallback macros for unsupported compilers.

How much performance improvement should I expect?

• if statements — likely() and unlikely() are used inside normal conditional branching.
• macros in C — these hints are commonly implemented as preprocessor macros.
• GCC built-in functions — __builtin_expect() is a compiler-provided builtin.
• branch prediction — the CPU and compiler both benefit from knowing which path is common.
• compiler optimization — branch hints are one small part of optimization.
• profile-guided optimization — a more data-driven alternative to manual branch hints.
• guard clauses — unlikely() is often used with early error returns.
• hot path vs cold path — these macros are mainly about optimizing the hot path and isolating the cold path.