Mojo function

black_box

black_box[T: AnyType, origin: Origin[mut=mut], //](ref [origin] value: T) -> ref [origin] T

Prevents the compiler from optimizing away computations or values.

Unlike black_box(take=...), this function takes a borrowed value and returns the value by reference.

This is an identity function that hints to the compiler to be maximally pessimistic about what it could do with the value. Unlike normal identity functions, black_box prevents the compiler from making assumptions about the input value or optimizing across the function call boundary.

The primary use case is in benchmarking, where you want to measure the performance of code as it would execute with unknown inputs at runtime, rather than with compile-time constants that the compiler can optimize away.

Notes:

Input expressions are still optimized before being passed to black_box. To prevent this, wrap operands individually.
If you do not need the return value, use keep() instead, which prevents optimization without returning the value.

Examples:

fn benchmark_contains():
    var haystack = "abcdefghijklmnopqrstuvwxyz"
    var needle = "lmnop"

    for _ in range(100):
        _ = haystack.contains(needle)

In the above example, the compiler/LLVM may make optimizations like: - needle and haystack are constant, it may move the call to contains outside the loop and delete the loop. - needle and haystack have values known at compile time, and contains is always True, replace the call to contains with a constant True. - Since the result of contains is unused, it may delete the function call entirely.

To prevent said optimizations, you can use black_box (and keep):

from benchmark import keep, black_box

fn benchmark_contains():
    var haystack = "abcdefghijklmnopqrstuvwxyz"
    var needle = "lmnop"

    for _ in range(100):
        # black_box:
        # Prevent the compiler from making assumptions about the input
        # values.
        var found_at = black_box(haystack).contains(black_box(needle))

        # keep:
        # Prevent the compiler from removing the call to `contains` even
        # though the result is unused.
        keep(found_at)

Parameters:

T (AnyType): The type of the value.
origin (Origin): The origin of the value.

Args:

value (T): The value to prevent optimization on.

Returns:

ref: The same value, but the compiler cannot make assumptions about it or optimize across this function boundary.

black_box[T: Movable, //](*, var take: T) -> T

Prevents the compiler from optimizing away computations or values.

Unlike black_box(ref T), this function takes an owned value and return the value by move.

Parameters:

T (Movable): The type of the value.

Args:

take (T): The value to prevent optimization on.

Returns:

T: The same value, but the compiler cannot make assumptions about it or optimize across this function boundary.