17fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin/* 2e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * Copyright (C) 2013 Google Inc. 37fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * 47fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * Licensed under the Apache License, Version 2.0 (the "License"); 57fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * you may not use this file except in compliance with the License. 67fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * You may obtain a copy of the License at 77fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * 87fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * http://www.apache.org/licenses/LICENSE-2.0 97fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * 107fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * Unless required by applicable law or agreed to in writing, software 117fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * distributed under the License is distributed on an "AS IS" BASIS, 127fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 137fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * See the License for the specific language governing permissions and 147fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin * limitations under the License. 157fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin */ 167fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin 177fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffinpackage com.google.caliper; 187fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin 19e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffinimport static java.lang.annotation.ElementType.METHOD; 20e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffinimport static java.lang.annotation.RetentionPolicy.RUNTIME; 21e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin 22e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffinimport java.lang.annotation.Retention; 23e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffinimport java.lang.annotation.Target; 247fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin 257fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin/** 26e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * Annotation for benchmark methods. To write a benchmark: 27e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 28e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <ol> 29e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <li>Annotate one or more methods with this annotation. 30e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <li>Annotate any fields with {@literal @}{@link Param} that should have parameter values 31e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * injected (see {@literal @}{@link Param} for more details) 32e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <li>Optionally use {@link BeforeExperiment} and {@link AfterExperiment} on setup and teardown 33e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * methods 34e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * </ol> 35e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 36e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <p>Since many benchmarks may execute in a shorter duration than is accurately measured by 37e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * available timers, benchmark methods <i>may</i> take either an {@code int} or {@code long} 38e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * argument representing a number of repetitions to perform in a given execution. It is critical 39e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * that the work done in the benchmark method scale linearly to the number of repetitions. 40e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 41e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <p>Benchmark methods may return any value. It will be ignored. 42e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 43e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <p>This class is instantiated and injected only once per child VM invocation, to measure one 44e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * particular combination of parameters. 45e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 46e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <p>For example: <pre> {@code 47e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * public final class MyBenchmark { 48e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * {@literal @}Param FeatureEnum feature; 49e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * {@literal @}Param({"1", "10", "100"}) int size; 50e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * private MyObject objectToBenchmark; 51e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 52e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * {@literal @}BeforeExperiment void initializeObject() { 53e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * objectToBenchmark = new MyObject(size); 54e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * } 55e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 56e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * {@literal @}Benchmark int foo(int reps) { 57e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * MyObject object = objectToBenchmark; // copy to local to avoid field access overhead 58e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * int dummy = 0; 59e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * for (int i = 0; i < reps; i++) { 60e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * dummy += object.foo(feature); 61e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * } 62e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * // return a dummy value so the JIT compiler doesn't optimize away the entire method. 63e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * return dummy; 64e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * } 65e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 66e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * {@literal @}Benchmark int bar() { 67e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * // benchmark another operation of MyObject that doesn't require a reps parameter 68e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * } 69e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * } 70e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * </pre> 71e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * 72e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * <p>The benchmark class MyBenchmark has two benchmark methods ({@code foo} and {@code bar}) and 73e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * two {@link Param Params} ({@code feature} and {@code size}). For each experiment performed by 74e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * Caliper (e.g. {@code foo} with {@code feature == FeatureEnum.A} and {@code size == 100}), 75e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin * {@code initializeObject} will be called exactly once, but {@code foo} may be called many times. 767fc0b45feb5ac6191547bb0a175a718cb41ec4f9Paul Duffin */ 77e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin@Target(METHOD) 78e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffin@Retention(RUNTIME) 79e236301e5fc778bffe1748ed80d7936e6c807012Paul Duffinpublic @interface Benchmark {} 80