BenchmarkState

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

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

Public companion functions

Unit
@BenchmarkState.Companion.ExperimentalExternalReport
reportData(
    className: String,
    testName: String,
    totalRunTimeNs: @IntRange(from = 0) Long,
    dataNs: List<Long>,
    warmupIterations: @IntRange(from = 0) Int,
    thermalThrottleSleepSeconds: @IntRange(from = 0) Long,
    repeatIterations: @IntRange(from = 1) Int
)

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

Public constructors

@ExperimentalBenchmarkStateApi
BenchmarkState(warmupCount: Int?, repeatCount: Int?)

Create a BenchmarkState for custom measurement behavior.

Public functions

List<Double>
Boolean

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

Unit

Stops the benchmark timer.

Unit

Resumes the benchmark timer.

Public companion functions

reportData

Added in 1.0.0
@BenchmarkState.Companion.ExperimentalExternalReport
fun reportData(
    className: String,
    testName: String,
    totalRunTimeNs: @IntRange(from = 0) Long,
    dataNs: List<Long>,
    warmupIterations: @IntRange(from = 0) Int,
    thermalThrottleSleepSeconds: @IntRange(from = 0) Long,
    repeatIterations: @IntRange(from = 1) 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: @IntRange(from = 0) Long

The total run time of the benchmark

dataNs: List<Long>

List of all measured timing results, in nanoseconds

warmupIterations: @IntRange(from = 0) Int

Number of iterations of warmup before measurements started. Should be no less than 0.

thermalThrottleSleepSeconds: @IntRange(from = 0) Long

Number of seconds benchmark was paused during thermal throttling.

repeatIterations: @IntRange(from = 1) Int

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

Public constructors

BenchmarkState

Added in 1.2.0
@ExperimentalBenchmarkStateApi
BenchmarkState(warmupCount: Int? = null, repeatCount: Int? = null)

Create a BenchmarkState for custom measurement behavior.

Parameters
warmupCount: Int? = null

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

repeatCount: Int? = null

Number of measurements to perform, leave null for default behavior

Public functions

getMeasurementTimeNs

Added in 1.2.0
@ExperimentalBenchmarkStateApi
fun getMeasurementTimeNs(): List<Double>

keepRunning

Added in 1.0.0
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

Added in 1.0.0
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);
}
}
Throws
kotlin.IllegalStateException

if the benchmark is already paused.

See also
resumeTiming

resumeTiming

Added in 1.0.0
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
kotlin.IllegalStateException

if the benchmark is already running.

See also
pauseTiming