Writing Directives
This topic examines Compiler Control options and steps for writing directives from those options.
Compiler Control Options
Options are instructions for compilation. Options provide method-context precision. Available options vary by compiler and require specific types of values.
Table 2-1 Common Options
Option | Description | Value Type | Default Value |
---|---|---|---|
|
Hides a directive and renders it unmatchable if it is set to |
|
|
|
Excludes methods from compilation. |
|
|
|
Sets a breakpoint to stop execution at the beginning of the specified methods when debugging the JVM. |
|
|
|
Sets a breakpoint to stop compilation at the beginning of the specified methods when debugging the JVM. |
|
|
|
Places only the specified methods in a log. You must first set the command-line option |
|
|
|
Prints assembly code for bytecoded and native methods by using the external |
|
|
|
Prints which methods are inlined, and where. |
|
|
|
Prints nmethods as they are generated. |
|
|
|
Compiles methods as a background task. Methods run in interpreter mode until the background compilation finishes. The value |
|
|
|
Enables the same |
|
|
|
Enables the same |
|
|
|
Enables the same |
|
|
|
Disregards all CompileCommands. |
|
|
|
Disables the use of intrinsics based on method-matching criteria. |
|
No default value. |
|
Forces or prevents inlining of a method based on method-matching criteria. See Writing an Inline Directive Option. |
|
No default value. |
Table 2-2 C2 Exclusive Options
Option | Description | Value Type | Default Value |
---|---|---|---|
|
Moves infrequent execution branches from the hot path. |
|
|
|
Prints generated assembly code after compilation by using the external |
|
|
|
Prints which intrinsic methods are used, and where. |
|
|
|
Traces pipelining information, similar to the corresponding global option, but on a per-method basis. This is intended for slow and fast debugging builds. |
|
|
|
Traces pipelining information, similar to the corresponding global option, but on a per-method basis. This is intended for slow and fast debugging builds. |
|
|
|
Traces variable spilling. |
|
|
|
Performs calculations in parallel, across vector registers. |
|
|
|
Performs calculations in parallel, across vector registers. This requires a debugging build of the JVM. |
|
|
|
Enables you to examine the |
|
|
|
Specifies the points where the compiler graph is printed in Oracle’s Hotspot Ideal Graphic Visualizer (IGV). A higher value means higher granularity. |
|
|
|
Sets the maximum number of nodes to use during a single method’s compilation. |
|
|
A ccstr
value type is a method pattern. See Writing a Method Pattern in a Compiler Directive.
The default directive supplies default values for compiler options. See What Is the Default Directive?
Writing a Directive File
Individual compiler directives are written in a directives file. Only directive files, not individual directives, can be added to the stack of active directives.
[ //Array of directives
{ //Directive Block
//Directive 1
match: ["java*.*", "oracle*.*"],
c1: {
Enable: true,
Exclude: true,
BreakAtExecute: true,
},
c2: {
Enable: false,
MaxNodeLimit: 1000,
},
BreakAtCompile: true,
DumpReplay: true,
},
{ //Directive Block
//Directive 2
match: ["*Concurrent.*"],
c2: {
Exclude:true,
},
},
]
Writing a Compiler Directive
You must write a compiler directive within a directives file. You can repeat the following steps for each individual compiler directive that you want to write in a directives file.
{
match: ["java*.*", "oracle*.*"],
c1: {
Enable: true,
Exclude: true,
BreakAtExecute: true,
},
c2: {
Enable: false,
MaxNodeLimit: 1000,
},
BreakAtCompile: true,
DumpReplay: true,
},
-
Extra trailing commas are optional in arrays and objects.
-
Attributes are strings and are optionally placed within quotation marks.
-
If an array contains only one element, then brackets are optional.
{
"match": "*Concurrent.*",
c2: {
"Exclude": true,
}
},
Writing a Method Pattern in a Compiler Directive
A ccstr
is a method pattern that you can write precisely or you can generalize with wildcard characters. You can specify what best-matching Java code should have accompanying directive options applied, or what Java code should be inlined.
Writing an Inline Directive Option
The attribute for an inline
directive option requires an array of method patterns with special commands prefixed. This indicates which method patterns should or shouldn’t inline.
- Write
inline:
in the common block, c1 block , or c2 block of a directive. - Add an array of carefully ordered method patterns. The prefixed command on the first matching method pattern is executed. The remaining method patterns in the array are ignored.
- Prefix a
+
to force inlining of any matching Java code. - Prefix a
-
to prevent inlining of any matching Java code. - Optional: If you need inlining behavior applied to multiple method patterns, then repeat Steps 1 to 4 to write multiple
inline
statements. Don’t write a single array that contains multiple method patterns.
inline
directive options:
inline: ["+java/lang*.*", "-sun*.*"]
inline: "+java/lang*.*"
Preventing Duplication with the Enable Option
You can use the Enable
option to hide aspects of directives and prevent duplication between directives.
c1
attribute of the compiler directives are identical.:[
{
match: ["java*.*"],
c1: {
BreakAtExecute: true,
BreakAtCompile: true,
DumpReplay: true,
DumpInline: true,
},
c2: {
MaxNodeLimit: 1000,
},
},
{
match: ["oracle*.*"],
c1: {
BreakAtExecute: true,
BreakAtCompile: true,
DumpReplay: true,
DumpInline: true,
},
c2: {
MaxNodeLimit: 2000,
},
},
]
The following example shows how the undesirable code duplication is resolved with the Enable
option. Enable
hides the block directives and renders them unmatchable. [
{
match: ["java*.*"],
c1: {
Enable: false,
},
c2: {
MaxNodeLimit: 1000,
},
},
{
match: ["oracle*.*"],
c1: {
Enable: false,
},
c2: {
MaxNodeLimit: 2000,
},
},
{
match: ["java*.*", "oracle*.*"],
c1: {
BreakAtExecute: true,
BreakAtCompile: true,
DumpReplay: true,
DumpInline: true,
},
c2: {
//Unreachable code
},
},
]
Typically, the first matching directive is applied to a method’s compilation. The Enable
option provides an exception to this rule. A method that would typically be compiled by c1
in the first or second directive is now compiled with the c1
block of the third directive. The c2
block of the third directive is unreachable because the c2
blocks in the first and second directive take priority.