1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
/*
* 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;
}
|
