3396b69fc9
Co-authored-by: Christian Hagedorn <chagedorn@openjdk.org> Co-authored-by: Tobias Hartmann <thartmann@openjdk.org> Reviewed-by: iignatyev
115 lines
6.4 KiB
Java
115 lines
6.4 KiB
Java
/*
|
|
* Copyright (c) 2021, 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.
|
|
*
|
|
* 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 compiler.lib.ir_framework;
|
|
|
|
import compiler.lib.ir_framework.shared.TestFormatException;
|
|
|
|
import java.lang.annotation.Retention;
|
|
import java.lang.annotation.RetentionPolicy;
|
|
|
|
/**
|
|
* Annotation for a check method of a <b>checked test</b>.
|
|
*
|
|
* <p>
|
|
* Let {@code t} be a test method specifying the {@link Test @Test} annotation and {@code c} be a check method specifying
|
|
* the {@code @Check(test = "t")} annotation. These two methods represent a so-called <i>checked test</i>. The only
|
|
* difference to a <i>base test</i> (see {@link Test}) is that the framework will invoke the check method {@code c}
|
|
* directly after the invocation of the test method {@code t} which allows to do some additional verification,
|
|
* including the return value of {@code t}. The framework does the following, similar as for <i>base tests</i>:
|
|
* <ol>
|
|
* <li><p>The framework warms {@code t} up by invoking it for a predefined number of iterations (default: 2000)
|
|
* or any number specified by an additional {@link Warmup @Warmup} annotation at {@code t} or by using
|
|
* {@link TestFramework#setDefaultWarmup(int)} (could also be 0 which skips the warm-up completely which is
|
|
* similar to simulating {@code -Xcomp}). After each invocation of {@code t}, the framework also invokes
|
|
* {@code c} if the {@code @Check} annotation specifies {@link CheckAt#EACH_INVOCATION} at {@link #when()}.
|
|
* More information about the warm-up in general can be found at {@link Warmup}</li>
|
|
* <li><p>After the warm-up, the framework compiles {@code t} at the specified compilation level set by
|
|
* {@link Test#compLevel()} (default {@link CompLevel#ANY} will pick the highest available level which is
|
|
* usually {@link CompLevel#C2}).</li>
|
|
* <li><p>The framework invokes {@code t} one more time to run the compilation. Afterwards, the framework will
|
|
* always invoke {@code c} again to be able perform additional checks after the compilation of {@code t}.</li>
|
|
* <li><p>The framework checks any specified {@link IR @IR} constraints at the test method {@code t}.
|
|
* More information about IR matching can be found at {@link IR}.</li>
|
|
* </ol>
|
|
*
|
|
* <p>
|
|
* The test method {@code t} has the same properties and follows the same constraints as stated in {@link Test}.
|
|
* <p>
|
|
* The following additional constraints must be met for the test method {@code t} and check method {@code c}:
|
|
* <ul>
|
|
* <li><p>{@code c} must specify the method name {@code t} as property in {@code @Check(test = "t")}
|
|
* (see {@link #test()}. Specifying a non-{@code @Test} annotated method or a {@code @Test} method that
|
|
* has already been used by another {@code @Check} or {@link Run @Run} method results in a {@link TestFormatException}.
|
|
* <li><p>{@code c} can specify the following method parameter combinations:
|
|
* <ul>
|
|
* <li><p>void</li>
|
|
* <li><p>One parameter: {@link TestInfo} which provides some information about {@code t} and utility methods.</li>
|
|
* <li><p>One parameter: the <i>exact</i> same type as the return value of {@code t}. When {@code c} is
|
|
* invoked by the framework, this parameter contains the return value of {@code t}.</li>
|
|
* <li><p>1st parameter: {@link TestInfo}; 2nd parameter: the <i>exact</i> same type as the return value of
|
|
* {@code t} (see above)</li>
|
|
* <li><p> Any other combination will result in a {@link TestFormatException}.
|
|
* </ul>
|
|
* <li><p>{@code c} is not compiled nor inlined.
|
|
* <li><p>{@code c} must be part of the test class. Using {@code @Check} in nested or other classes is not allowed.</li>
|
|
* <li><p>{@code c} cannot specify any helper-method-specific compile command annotations
|
|
* ({@link ForceCompile @ForceCompile}, {@link DontCompile @DontCompile}, {@link ForceInline @ForceInline},
|
|
* {@link DontInline @DontInline}).</li>
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* If no verification is required, use a <i>base test</i> (see {@link Test}). If {@code t} must be invoked with more
|
|
* complex or varying arguments and/or the {@code t} must be invoked differently in subsequent invocations, use a
|
|
* <i>custom run test</i> (see {@link Run}).
|
|
*
|
|
* <p>
|
|
* Examples on how to write checked tests can be found in {@link jdk.test.lib.hotspot.ir_framework.examples.CheckedTestExample}
|
|
* and also as part of the internal testing in the package {@link jdk.test.lib.hotspot.ir_framework.tests}.
|
|
*
|
|
* @see Test
|
|
* @see TestInfo
|
|
* @see CheckAt
|
|
*/
|
|
@Retention(RetentionPolicy.RUNTIME)
|
|
public @interface Check {
|
|
/**
|
|
* The unique associated {@link Test} method for this {@code @Check} annotated check method. The framework will directly
|
|
* invoke the {@code @Check} method after each invocation or only after the compilation of the associated {@code @Test}
|
|
* method (depending on the value set with {@link #when()}).
|
|
* <p>
|
|
* If a non-{@code @Test} annotated method or a {@code @Test} method that has already been used by another
|
|
* {@code @Check} or {@link Run} method is specified, then a {@link TestFormatException} is thrown.
|
|
*
|
|
* @see Test
|
|
*/
|
|
String test();
|
|
/**
|
|
* When should the {@code @Check} method be invoked? By default, the check is done after each invocation which is
|
|
* encouraged if performance is not critical.
|
|
*
|
|
* @see CheckAt
|
|
*/
|
|
CheckAt when() default CheckAt.EACH_INVOCATION;
|
|
}
|