BenchmarkState

Kotlin |Java

class BenchmarkState

kotlin.Any
↳	androidx.benchmark.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);
    }
}

Summary

Nested classes
annotation	ExperimentalExternalReport

Public constructors
<init>() Control object for benchmarking in the code in Java.

Public methods
Long	getMinTimeNanos()
Boolean	keepRunning() Returns true if the benchmark needs more samples - use this as the condition of a while loop.
Unit	pauseTiming() Stops the benchmark timer.
Unit	resumeTiming() Resumes the benchmark timer.

Companion functions
Unit	reportData(className: String, testName: String, @IntRange(0) totalRunTimeNs: Long, dataNs: List<Long>, @IntRange(0) warmupIterations: Int, @IntRange(0) thermalThrottleSleepSeconds: Long, @IntRange(1) repeatIterations: Int) Hooks for benchmarks not using androidx.benchmark.junit4.BenchmarkRule to register results.

Public constructors

<init>

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

• androidx.benchmark.junit4.BenchmarkRule

Public methods

getMinTimeNanos

fun getMinTimeNanos(): Long

keepRunning

fun keepRunning(): Boolean

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

fun pauseTiming(): Unit

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);
    }
}

Exceptions
IllegalStateException	if the benchmark is already paused.

See Also

• resumeTiming

resumeTiming

fun resumeTiming(): Unit

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 [IllegalStateException] if the benchmark is already running.

See Also

• pauseTiming

Companion functions

reportData

@JvmStatic fun reportData(
    className: String, 
    testName: String, 
    @IntRange(0) totalRunTimeNs: Long, 
    dataNs: List<Long>, 
    @IntRange(0) warmupIterations: Int, 
    @IntRange(0) thermalThrottleSleepSeconds: Long, 
    @IntRange(1) repeatIterations: Int
): Unit

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
className: String	Name of class the benchmark runs in
testName: String	Name of the benchmark
totalRunTimeNs: Long	The total run time of the benchmark
dataNs: List<Long>	List of all measured timing results, in nanoseconds
warmupIterations: Int	Number of iterations of warmup before measurements started. Should be no less than 0.
thermalThrottleSleepSeconds: Long	Number of seconds benchmark was paused during thermal throttling.
repeatIterations: Int	Number of iterations in between each measurement. Should be no less than 1.