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>()

Public methods
Long	getMin() Used for testing in other modules
Boolean	keepRunning() Returns true if the benchmark needs more samples - use this as the condition of a while loop.
Boolean	keepRunningInline() Inline fast-path function for inner benchmark loop.
Unit	pauseTiming() Stops the benchmark timer.
Unit	report(fullClassName: String, simpleClassName: String, methodName: String)
Unit	resumeTiming() Resumes the benchmark timer.

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

Public constructors

<init>

BenchmarkState()

Public methods

getMin

fun getMin(): Long

Used for testing in other modules

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

keepRunningInline

inline fun keepRunningInline(): Boolean

Inline fast-path function for inner benchmark loop.

Kotlin users should use BenchmarkRule.measureRepeated

This codepath uses exclusively @JvmField/const members, so there are no method calls at all in the inlined loop. On recent Android Platform versions, ART inlines these accessors anyway, but we want to be sure it's as simple as possible.

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

report

fun report(
    fullClassName: String, 
    simpleClassName: String, 
    methodName: String
): Unit

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, 
    totalRunTimeNs: Long, 
    dataNs: List<Long>, 
    warmupIterations: Int, 
    thermalThrottleSleepSeconds: Long, 
    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 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.