1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.rng.examples.jmh.core; 19 20 import org.apache.commons.rng.UniformRandomProvider; 21 import org.apache.commons.rng.simple.RandomSource; 22 import org.openjdk.jmh.annotations.Level; 23 import org.openjdk.jmh.annotations.Param; 24 import org.openjdk.jmh.annotations.Scope; 25 import org.openjdk.jmh.annotations.Setup; 26 import org.openjdk.jmh.annotations.State; 27 28 /** 29 * A benchmark state that can retrieve the various generators defined by {@link RandomSource} 30 * values. 31 * 32 * <p>The state will include only those that do not require additional constructor arguments.</p> 33 * 34 * <p>This class is abstract since it adds a special {@code RandomSource} named 35 * {@code BASELINE}. A baseline implementation for the {@link UniformRandomProvider} 36 * interface must be provided by implementing classes. For example to baseline methods 37 * using {@link UniformRandomProvider#nextInt()} use the following code:</p> 38 * 39 * <pre> 40 * @State(Scope.Benchmark) 41 * public static class Sources extends BaselineSources { 42 * @Override 43 * protected UniformRandomProvider createBaseline() { 44 * return BaselineUtils.getNextInt(); 45 * } 46 * } 47 * </pre> 48 * 49 * <p>Note: It is left to the implementation to ensure the baseline is suitable for the method 50 * being tested.</p> 51 */ 52 @State(Scope.Benchmark) 53 public abstract class BaselineSources { 54 /** The keyword identifying the baseline implementation. */ 55 private static final String BASELINE = "BASELINE"; 56 57 /** 58 * RNG providers. 59 * 60 * <p>List all providers that do not require additional constructor arguments. This list 61 * is in the declared order of {@link RandomSource}.</p> 62 */ 63 @Param({BASELINE, 64 "JDK", 65 "WELL_512_A", 66 "WELL_1024_A", 67 "WELL_19937_A", 68 "WELL_19937_C", 69 "WELL_44497_A", 70 "WELL_44497_B", 71 "MT", 72 "ISAAC", 73 "SPLIT_MIX_64", 74 "XOR_SHIFT_1024_S", 75 "TWO_CMRES", 76 "MT_64", 77 "MWC_256", 78 "KISS", 79 "XOR_SHIFT_1024_S_PHI", 80 "XO_RO_SHI_RO_64_S", 81 "XO_RO_SHI_RO_64_SS", 82 "XO_SHI_RO_128_PLUS", 83 "XO_SHI_RO_128_SS", 84 "XO_RO_SHI_RO_128_PLUS", 85 "XO_RO_SHI_RO_128_SS", 86 "XO_SHI_RO_256_PLUS", 87 "XO_SHI_RO_256_SS", 88 "XO_SHI_RO_512_PLUS", 89 "XO_SHI_RO_512_SS", 90 "PCG_XSH_RR_32", 91 "PCG_XSH_RS_32", 92 "PCG_RXS_M_XS_64", 93 "PCG_MCG_XSH_RR_32", 94 "PCG_MCG_XSH_RS_32", 95 "MSWS", 96 "SFC_32", 97 "SFC_64", 98 "JSF_32", 99 "JSF_64", 100 "XO_SHI_RO_128_PP", 101 "XO_RO_SHI_RO_128_PP", 102 "XO_SHI_RO_256_PP", 103 "XO_SHI_RO_512_PP", 104 "XO_RO_SHI_RO_1024_PP", 105 "XO_RO_SHI_RO_1024_S", 106 "XO_RO_SHI_RO_1024_SS", 107 }) 108 private String randomSourceName; 109 110 /** RNG. */ 111 private UniformRandomProvider provider; 112 113 /** 114 * Gets the generator. 115 * 116 * @return the RNG. 117 */ 118 public UniformRandomProvider getGenerator() { 119 return provider; 120 } 121 122 /** Instantiates generator. This need only be done once per set of iterations. */ 123 @Setup(Level.Trial) 124 public void setup() { 125 if (BASELINE.equals(randomSourceName)) { 126 provider = createBaseline(); 127 } else { 128 final RandomSource randomSource = RandomSource.valueOf(randomSourceName); 129 provider = RandomSource.create(randomSource); 130 } 131 } 132 133 /** 134 * Creates the baseline {@link UniformRandomProvider}. 135 * 136 * <p>This should implement the method(s) that will be tested. The speed of this RNG is expected 137 * to create a baseline against which all other generators will be compared.</p> 138 * 139 * @return the baseline RNG. 140 */ 141 protected abstract UniformRandomProvider createBaseline(); 142 }