| /* |
| * Copyright (C) 2013 Google Inc. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.google.caliper; |
| |
| import static java.lang.annotation.ElementType.METHOD; |
| import static java.lang.annotation.RetentionPolicy.RUNTIME; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.Target; |
| |
| /** |
| * Annotation for benchmark methods. To write a benchmark: |
| * |
| * <ol> |
| * <li>Annotate one or more methods with this annotation. |
| * <li>Annotate any fields with {@literal @}{@link Param} that should have parameter values |
| * injected (see {@literal @}{@link Param} for more details) |
| * <li>Optionally use {@link BeforeExperiment} and {@link AfterExperiment} on setup and teardown |
| * methods |
| * </ol> |
| * |
| * <p>Since many benchmarks may execute in a shorter duration than is accurately measured by |
| * available timers, benchmark methods <i>may</i> take either an {@code int} or {@code long} |
| * argument representing a number of repetitions to perform in a given execution. It is critical |
| * that the work done in the benchmark method scale linearly to the number of repetitions. |
| * |
| * <p>Benchmark methods may return any value. It will be ignored. |
| * |
| * <p>This class is instantiated and injected only once per child VM invocation, to measure one |
| * particular combination of parameters. |
| * |
| * <p>For example: <pre> {@code |
| * public final class MyBenchmark { |
| * {@literal @}Param FeatureEnum feature; |
| * {@literal @}Param({"1", "10", "100"}) int size; |
| * private MyObject objectToBenchmark; |
| * |
| * {@literal @}BeforeExperiment void initializeObject() { |
| * objectToBenchmark = new MyObject(size); |
| * } |
| * |
| * {@literal @}Benchmark int foo(int reps) { |
| * MyObject object = objectToBenchmark; // copy to local to avoid field access overhead |
| * int dummy = 0; |
| * for (int i = 0; i < reps; i++) { |
| * dummy += object.foo(feature); |
| * } |
| * // return a dummy value so the JIT compiler doesn't optimize away the entire method. |
| * return dummy; |
| * } |
| * |
| * {@literal @}Benchmark int bar() { |
| * // benchmark another operation of MyObject that doesn't require a reps parameter |
| * } |
| * } |
| * </pre> |
| * |
| * <p>The benchmark class MyBenchmark has two benchmark methods ({@code foo} and {@code bar}) and |
| * two {@link Param Params} ({@code feature} and {@code size}). For each experiment performed by |
| * Caliper (e.g. {@code foo} with {@code feature == FeatureEnum.A} and {@code size == 100}), |
| * {@code initializeObject} will be called exactly once, but {@code foo} may be called many times. |
| */ |
| @Target(METHOD) |
| @Retention(RUNTIME) |
| public @interface Benchmark {} |