org.openjdk.jmh.annotations.Benchmark Maven / Gradle / Ivy
/*
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package org.openjdk.jmh.annotations;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* {@link Benchmark} annotates the benchmark method.
*
* JMH will produce the generated benchmark code for this method during compilation,
* register this method as the benchmark in the benchmark list, read out the default
* values from the annotations, and generally prepare the environment for the benchmark
* to run.
*
* Benchmarks may use annotations to control different things in their operations.
* See {@link org.openjdk.jmh.annotations} package for available annotations, read their
* Javadocs, and/or look through
*
* JMH samples for their canonical uses. As the rule of thumb, most annotations
* may be placed either at the {@link Benchmark} method, or at the enclosing class,
* to be inherited by all {@link Benchmark} methods in the class.
*
* {@link Benchmark} demarcates the benchmark payload, and JMH treats it specifically
* as the wrapper which contains the benchmark code. In order to run the benchmark reliably,
* JMH enforces a few stringent properties for these wrapper methods, including, but not
* limited to:
*
* - Method should be public
* - Arguments may only include either {@link State} classes, which JMH will inject
* while calling the method (see {@link State} for more details), or JMH infrastructure
* classes, like {@link org.openjdk.jmh.infra.Control}, or {@link org.openjdk.jmh.infra.Blackhole}
* - Method can only be synchronized if a relevant {@link State} is placed
* on the enclosing class.
*
*
* If you want to benchmark methods that break these properties, you have to write them
* out as distinct methods and call them from {@link Benchmark} method.
*
* Benchmark method may declare Exceptions and Throwables to throw. Any exception actually
* raised and thrown will be treated as benchmark failure.
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Benchmark {
}