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
|
/*
* 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 run method of a <b>custom run test</b>.
*
* <p>
* Let {@code t} be a test method specifying the {@link Test @Test} annotation and {@code r} be a run method specifying
* the {@code @Run(test = "t")} annotation. These two methods represent a so-called <i>custom run test</i>. The only
* difference to a <i>base test</i> (see {@link Test}) is that the framework will not invoke the test method {@code t}
* but instead the run method {@code r} which is then responsible to invoke {@code t} in any way and optionally do any
* additional verification (e.g. of the return value). If {@code r} does not specify {@link RunMode#STANDALONE} as
* {@link #mode()} property, the framework does the following, similar as for <i>base tests</i>:
* <ol>
* <li><p>The framework warms {@code r} up by invoking it for a predefined number of iterations (default: 2000)
* or any number specified by an additional {@link Warmup} annotation at the run method {@code r} or by using
* {@link TestFramework#setDefaultWarmup(int)} (could also be 0 which skips the warm-up completely which is
* similar to simulating {@code -Xcomp}). More information about the warm-up in general can be found in
* {@link Warmup @Warmup}.</li>
* <li><p>After the warm-up, the framework compiles the test method {@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 the run method {@code r} one more time to check the compilation.</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>
* If {@code r} specifies {@link RunMode#STANDALONE} as {@link #mode()} property, the framework gives complete
* control to the run method {@code r}:
* <ol>
* <li><p>The framework invokes the run method {@code r} only one time without any warm-up or compilation of
* {@code t} ({@link Warmup @Warmup} is not allowed at {@code r} in this case).</li>
* <li><p>After this single invocation, the framework directly checks any specified {@link IR} constraints at the test
* method {@code t}. The run method {@code r} needs to make sure to reliably trigger a C2 compilation. Otherwise,
* IR matching will fail. More information about IR matching can be found at {@link IR}.</li>
* </ol>
*
* <p>
* The test method {@code t} and run method {@code r} have the following properties:
* <ul>
* <li><p>{@code t} can specify any parameter or return type except {@link AbstractInfo} or any of its subclasses.</li>
* <li><p>{@code t} is not inlined.
* <li><p>{@code r} is not compiled nor inlined.
* <li><p>{@code r} is responsible to invoke {@code t} in any way (once, multiple times or even skipping on some
* invocations of {@code r}).
* <li><p>{@code r} can specify the following method parameter combinations:
* <ul>
* <li><p>void</li>
* <li><p>One parameter: {@link RunInfo} which provides some information about {@code t} and utility methods.</li>
* <li><p>Any other combination will result in a {@link TestFormatException}.
* </ul>
* <li><p>{@code t} and {@code r} must be part of the test class. Using {@code @Run} and {@code @Test} in nested or
* other helper classes is not allowed.</li>
* <li><p>{@code t} and {@code r} cannot specify any helper-method-specific compile command annotations
* ({@link ForceCompile @ForceCompile}, {@link DontCompile @DontCompile}, {@link ForceInline @ForceInline},
* {@link DontInline @DontInline}).</li>
* </ul>
*
* <p>
* Examples on how to write custom run tests can be found in {@link jdk.test.lib.hotspot.ir_framework.examples.CustomRunTestExample}
* and also as part of the internal testing in the package {@link jdk.test.lib.hotspot.ir_framework.tests}.
*
* @see Test
* @see RunInfo
* @see RunMode
*/
@Retention(RetentionPolicy.RUNTIME)
public @interface Run {
/**
* The associated {@link Test @Test} methods (one or more) for this {@code @Run} annotated run method.
* The framework directly invokes the run method instead of the associated {@code @Test} methods.
*/
String[] test();
/**
* The mode of this custom run test.
*
* @see RunMode
*/
RunMode mode() default RunMode.NORMAL;
}
|
