org.openjdk.jmh.annotations

Enum Level

java.lang.Object

java.lang.Enum<Level>

org.openjdk.jmh.annotations.Level

All Implemented Interfaces:

Serializable, Comparable<Level>

public enum Level
extends Enum<Level>

Control when to run the fixture methods.

See Also:

Setup, TearDown

Enum Constant Summary

Enum Constants

Enum Constant and Description
Invocation Invocation level: to be executed for each benchmark method execution.
Iteration Iteration level: to be executed before/after each iteration of the benchmark.
Trial Trial level: to be executed before/after each run of the benchmark.

Method Summary

Modifier and Type	Method and Description
static Level	valueOf(String name) Returns the enum constant of this type with the specified name.
static Level[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

Trial

public static final Level Trial

Trial level: to be executed before/after each run of the benchmark.

Trial is the set of benchmark iterations.

Iteration

public static final Level Iteration

Iteration level: to be executed before/after each iteration of the benchmark.

Iteration is the set of benchmark invocations.

Invocation

public static final Level Invocation

Invocation level: to be executed for each benchmark method execution.

WARNING: HERE BE DRAGONS! THIS IS A SHARP TOOL. MAKE SURE YOU UNDERSTAND THE REASONING AND THE IMPLICATIONS OF THE WARNINGS BELOW BEFORE EVEN CONSIDERING USING THIS LEVEL.

This level is only usable for benchmarks taking more than a millisecond per single Benchmark method invocation. It is a good idea to validate the impact for your case on ad-hoc basis as well.

WARNING #1: Since we have to subtract the setup/teardown costs from the benchmark time, on this level, we have to timestamp *each* benchmark invocation. If the benchmarked method is small, then we saturate the system with timestamp requests, which introduce artificial latency, throughput, and scalability bottlenecks.

WARNING #2: Since we measure individual invocation timings with this level, we probably set ourselves up for (coordinated) omission. That means the hiccups in measurement can be hidden from timing measurement, and can introduce surprising results. For example, when we use timings to understand the benchmark throughput, the omitted timing measurement will result in lower aggregate time, and fictionally *larger* throughput.

WARNING #3: In order to maintain the same sharing behavior as other Levels, we sometimes have to synchronize (arbitrage) the access to State objects. Other levels do this outside the measurement, but at this level, we have to synchronize on *critical path*, further offsetting the measurement.

WARNING #4: Current implementation allows the helper method execution at this Level to overlap with the benchmark invocation itself in order to simplify arbitrage. That matters in multi-threaded benchmarks, when one worker thread executing Benchmark method may observe other worker thread already calling TearDown for the same object.

Method Detail

values

public static Level[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (Level c : Level.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Level valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null