BenchmarkState

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

Public constructors

Public methods

Long

Used for testing in other modules

Boolean

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

Boolean

Inline fast-path function for inner benchmark loop.

Unit

Stops the benchmark timer.

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

Unit

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

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

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