BenchmarkState

public final class BenchmarkState

Control object for benchmarking in the code in Java.

Query a state object with androidx.benchmark.junit4.BenchmarkRule.getState, and use it to measure a block of Java with BenchmarkState.keepRunning:

@Rule
public BenchmarkRule benchmarkRule = new BenchmarkRule();

@Test
public void sampleMethod() {
    BenchmarkState state = benchmarkRule.getState();

    int[] src = new int[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
    while (state.keepRunning()) {
        int[] dest = new int[src.length];
        System.arraycopy(src, 0, dest, 0, src.length);
    }
}
See also
BenchmarkRule

#getState()

Summary

Nested types
public static class BenchmarkState.Companion
@RequiresOptIn
@Retention(value = AnnotationRetention.BINARY)
@Target(allowedTargets = [AnnotationTarget.FUNCTION])
public annotation BenchmarkState.Companion.ExperimentalExternalReport

Public constructors

Create a BenchmarkState for custom measurement behavior.

Public methods
final @NonNull List<@NonNull Double>
final boolean

Returns true if the benchmark needs more samples - use this as the condition of a while loop.
final void

Stops the benchmark timer.
static final void
@BenchmarkState.Companion.ExperimentalExternalReport
reportData(
    @NonNull String className,
    @NonNull String testName,
    @IntRange(from = 0) long totalRunTimeNs,
    @NonNull List<@NonNull Long> dataNs,
    @IntRange(from = 0) int warmupIterations,
    @IntRange(from = 0) long thermalThrottleSleepSeconds,
    @IntRange(from = 1) int repeatIterations
)

Hooks for benchmarks not using androidx.benchmark.junit4.BenchmarkRule to register results.
final void

Resumes the benchmark timer.

Public constructors

BenchmarkState

Added in 1.2.0
@ExperimentalBenchmarkStateApi
public BenchmarkState(Integer warmupCount, Integer repeatCount)

Create a BenchmarkState for custom measurement behavior.

Parameters
Integer warmupCount

Number of non-measured warmup iterations to perform, leave null to determine automatically
Integer repeatCount

Number of measurements to perform, leave null for default behavior

Public methods

getMeasurementTimeNs

Added in 1.2.0
@ExperimentalBenchmarkStateApi
public final @NonNull List<@NonNull Double> getMeasurementTimeNs()

keepRunning

Added in 1.0.0
public final boolean keepRunning()

Returns true if the benchmark needs more samples - use this as the condition of a while loop.

while (state.keepRunning()) {
    int[] dest = new int[src.length];
    System.arraycopy(src, 0, dest, 0, src.length);
}

pauseTiming

Added in 1.0.0
public final void pauseTiming()

Stops the benchmark timer.

This method can be called only when the timer is running.

@Test
public void bitmapProcessing() {
    final BenchmarkState state = mBenchmarkRule.getState();
    while (state.keepRunning()) {
        state.pauseTiming();
        // disable timing while constructing test input
        Bitmap input = constructTestBitmap();
        state.resumeTiming();

        processBitmap(input);
    }
}
Throws
kotlin.IllegalStateException

if the benchmark is already paused.
See also
resumeTiming

reportData

Added in 1.0.0
@BenchmarkState.Companion.ExperimentalExternalReport
public static final void reportData(
    @NonNull String className,
    @NonNull String testName,
    @IntRange(from = 0) long totalRunTimeNs,
    @NonNull List<@NonNull Long> dataNs,
    @IntRange(from = 0) int warmupIterations,
    @IntRange(from = 0) long thermalThrottleSleepSeconds,
    @IntRange(from = 1) int repeatIterations
)

Hooks for benchmarks not using androidx.benchmark.junit4.BenchmarkRule to register results.

Results are printed to Studio console, and added to the output JSON file.

Parameters
@NonNull String className

Name of class the benchmark runs in
@NonNull String testName

Name of the benchmark
@IntRange(from = 0) long totalRunTimeNs

The total run time of the benchmark
@NonNull List<@NonNull Long> dataNs

List of all measured timing results, in nanoseconds
@IntRange(from = 0) int warmupIterations

Number of iterations of warmup before measurements started. Should be no less than 0.
@IntRange(from = 0) long thermalThrottleSleepSeconds

Number of seconds benchmark was paused during thermal throttling.
@IntRange(from = 1) int repeatIterations

Number of iterations in between each measurement. Should be no less than 1.

resumeTiming

Added in 1.0.0
public final void resumeTiming()

Resumes the benchmark timer.

This method can be called only when the timer is stopped.

@Test
public void bitmapProcessing() {
    final BenchmarkState state = mBenchmarkRule.getState();
    while (state.keepRunning()) {
        state.pauseTiming();
        // disable timing while constructing test input
        Bitmap input = constructTestBitmap();
        state.resumeTiming();

        processBitmap(input);
    }
}
Throws
kotlin.IllegalStateException

if the benchmark is already running.
See also
pauseTiming