JEP 165: Compiler Control

OwnerNils Eliasson
Created2011/12/02 20:00
Updated2014/12/19 13:53
TypeFeature
StatusTargeted
Componenthotspot / compiler
ScopeJDK
Discussionhotspot dash compiler dash dev at openjdk dot java dot net
EffortM
DurationM
Priority2
Reviewed byJesper Wilhelmsson
Endorsed byMikael Vidstedt
Release9
Issue8046155

Summary

This JEP will improve the control of the JVM compilers. It will allow the user to apply sets of options depending on which method is being compiled. It also adds the possibility of changing the option sets during run time.

Goals

Motivation

Method-context dependent control of the compilation process is a powerful tool for writing small contained JVM compiler tests that can be run without restarting the entire JVM. It is also very useful for creating workarounds for bugs in the JVM compilers. A good encapsulation of the compiler options is also good hygiene.

Description

Directives

All options that control the JVM compilers will be gathered into a set of options. A set of options with values is called a compiler directive and is an instruction for how to compile. A directive is supplied to the VM together with a method matcher that decides what methods it applies to. Several directives can be active in the runtime at the same time but only one is applied to a specific compilation. Directives can be added and removed during run time.

Directives format

Directives files have a specified standardized and human readable file format. Directives files can be loaded via command line and diagnostic command. A directives file has one or more defined directives. A directive contains one method pattern and a number of options with values. The order of the directives are significant. The compilerBroker will apply the first directive whose pattern match to a compilation.

The directives file format will be a subset of JSON with some additions. The format deviates from JSON in the following manners:

The file can use all UTF-8 charcters as supported by the JVM specification. These characters are reserved for the file format:

 { - curly brace open
 } - curly brace end
 [ - square brace open
 ] - square brace end
 " - quoutes
 : - colon
 , - comma

Directives Example 1

[    // Start if array of directives
    {   // Start of directive block
        // Excactly one match with one or several patterns
        // The array is not required with a single pattern
        match: ["java*.*", "oracle*.*"],   
        // A directives block that only apply to a single compiler
        c1: {   
             // A bool option. Extra trailing comma should not cause a parse error 
             print_assembly:true,  
        },
        // Another compiler block
        c2: {
             // force inline patters prepended with +, prevent with -
             inline: ["+vm*.*","-*.*" ] 
        },
        // Options outside compiler block apply to all compilers
        break:true   // enable break in compiled code 
    },
    {  // start of another directives block
        // match ant method whose class contain 'Concurrent'
        match: ["*Concurrent.*"],    
        c2: {
             // disable compilation
             enable:false,    
        }    
        // with the c1 directive unspecified the options remains default.
    }
]   

Directives Example 2

[   
   {   
         // pattern to match against class+method+signature
         // leading and trailing wildcard (*) allowed
         match: "apa.Dingo.*",

         // override defaults for specified compiler
         // the innermost option has the highest prority
         c1: {
           //override c1 presets 
           array_bounds_check_removal: false
         }

         c2: {
           // control inlining of method
           // + force inline, - dont inline
           inline : [ "+java.util.*", "-com.sun.*"],
         }

         // directives outside a specific preset applies to all compilers          
         inline : [ "+java.util.*", "-com.sun.*"],
         print_assembly: true,
         verify_oopmaps: true,
         max_loop_unrolling: 5
   },
   {
         // matching several patterns require an array
         match: ["gorilla.*","chimpans*"]

         c2: {
              // Turn off c2 copmpiler
              // All compilers are on by default
              enable:false
         }

         // applies to all compilers                   
         // + force inline, - dont inline
         inline : [ "+java.util.*", "-com.sun.*"],         
         print_inlining: true,

         // force matching compiles to be blocking/syncronous
         blocking compile: true
   },
]

Directives options list

The first implementation goal is to add the relevant options from CompilerOracle:

break:<bool>
Control a debug breakpoint in the method entry

break_compiler:<bool> 
Control a debug breakpoint in the start of the compilation

print_assembly:<bool> 
Control print_assembly

print_ideal:<bool> 
Control print ideal graph for method

inline:<one pattern or an array of string patterns>
The pattern is a string that matches a method name in the same way as directives are matched. 
A '+' prepended to the pattern signifies that methods matching should be force-inlined. 
A '-' that it should be prevented from inlining. 
The command from the first pattern that matches is used. 
Example1: inline:["+java/lang/*.*", -"sun*.*"]
Example2: inline:"+java/lang/*.*"

log:<bool> 
Enable log compilation of method

blocking_compile:<bool>
Control if the method should be compiled synchronously

enable:<bool>
Can only be listed inside a compiler block
Controls if a compiler is allowed to compile this method

<compiler name>: <directives block>
Options inside the directives block only apply to that specific compiler.
These options override options in the generic directives scope
The available compilers are currently: c1 and c2
Compiler levels can be supported later but are not part of the initial task

Directives patterns

Method patterns that are used in the "match" and "inline"-option has the following patterns: Class.method(signature)

Class includes package names separated by a / Class and method can be wildcarded with a leading and trailing *, or substituted for a * If the signature is left out it defaults to *

These are valid patterns: "java/lang/String,indexOf" "/lang/String,indexOf(I)" "java/lang/String.(I)" "java/lang/String.()" "." "java/lang/."

Directives parser

The directives parser is responsible for parsing the directives file and adding the information to an VM internal format.

If a malformed directives file is specified on the command line the VM will print an error and exit. If a malformed directives file is added through diagnostic command it will be ignored and a proper warning will be printed.

The parser will validate that all options are valid. Platform dependent options will print warnings on platforms that do not support them. The rationale is that the same directives files should be usable regardless of which platform it is deployed on.

Unspecified options will use the default value. If a command line option is specified that will be the default value. The default value for the method pattern is "." (match all methods).

CompilerBroker

The compilerBroker has a directives stack that contains all applied directives. The bottom directive is the default set and can never be removed. When a file is loaded with additional directives they will be added in reverse order, with the first directive in the file ending up on top of the stack. This is a usability feature.

When a method is submitted for a compilation - the compilerBroker will select first directive that matches and pass it to the compiler. The compilerBroker and compilers will ignore options that would create bad code (forcing a hardware instruction on a platform that doesn't support it for example) and a proper warning will be emitted. The directives options has the same limitations as the normal commandline flags - for example forcing inlinings will only be respected as long the IR don't grow to large.

Command line interface

A directives file can be added one the command line. The VM will exit with an error message if the flag is wrong (normal commandline parsing), the file is missing, or if the file contents are malformed.

-XX:CompilerControl=<file>

Diagnostic command interface

These are the diagnostic commands that will be used with compiler control:

jcmd <pid> Compiler.add_directives <file>   
Add additional directives from the file. The new directives will be added on top of the old, with the first directive in the file ending up on the top of the directives stack.

jcmd <pid> Compiler.list_directives        
List all directives on the directives stack from top to bottom.

jcmd <pid> Compiler.clear_directives     
Clear the directives stack

jcmd <pid> Compiler.remove_directives     
Remove the top element from the directives stack

Error handling

Add the possibility of dumping the directives stack when the VM enters a fatal state.

-XX:+CompilerControlDumpOnCrash

Risks and Assumptions

The sheer amount of compiler options will limit us to focus on a subset initially. We will focus on a subset and expand from there.

Dependences

Impact