Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8046155

JEP 165: Compiler Control



    • Nils Eliasson
    • Feature
    • Open
    • JDK
    • hotspot dash compiler dash dev at openjdk dot java dot net
    • M
    • M
    • 165



      This JEP proposes an improved way to control the JVM compilers. It enables runtime manageable, method dependent compiler flags. (Immutable for the duration of a compilation.)


      • Fine-grained and method-context dependent control of the JVM compilers (C1 and C2)

      • The ability to change the JVM compiler control options in run time

      • No performance degradation


      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.



      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:

      • Only support numbers that is compatible with the command line options - int and doubles.
      • Comments are allowed - lines starting with "//"
      • Extra trailing ''," are allowed in arrays and objects
      • Escaped characters will probably not be allowed (TBD)
      • Option names are strings but are optionally quoted

      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 
              // Another compiler block
              c2: {
                   // force inline patters prepended with +, prevent with -
                   inline: ["+vm*::*","-*::*" ] 
              // Options outside compiler block apply to all compilers
              BreakAtExecute: true   // enable break in compiled code 
              BreakAtCompile: true   // enable break in compiler
          {  // start of another directives block
              // match ant method whose class end with 'Concurrent'
              match: ["*Concurrent::*"],    
              c2: {
                   // disable compilation
              // 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 priority
               c1: {
                 //override c1 presets 
                 PrintInlining: false  // Example - this option may not exist
               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::*"],
               PrintAssembly: true
               // matching several patterns require an array
               match: ["steve::*","alex::*"]
               c2: {
                    Enable: false,    // Ignore this directive for c2. 
                    BreakAtExecute: true // This will not be applied since Enable is false above                  
               // applies to all compilers                   
               // + force inline, - dont inline
               inline : [ "+java.util::*", "-com.sun::*"],         
               PrintInlining: true

      Directives options list

      The first implementation contains the following options. All options have previously been used in CompileCommand option commands. More options will be added.

      Common flags: Enable, bool Exclude, bool BreakAtExecute, bool BreakAtCompile, bool Log, bool PrintAssembly, bool PrintInlining, bool PrintNMethods, bool ReplayInline, bool DumpReplay, bool DumpInline, bool CompilerDirectivesIgnoreCompileCommands, bool Inline, ccstr[]

      C2 only: BlockLayoutByFrequency, bool PrintOptoAssembly, bool PrintIntrinsics, bool raceOptoPipelining, bool TraceOptoOutput, bool TraceSpilling, bool Vectorize, bool VectorizeDebug, bool CloneMapDebug, bool IGVPrintLevel, intx MaxNodeLimit, intx DisableIntrinsics, ccstr

      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.*::*"

      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" "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).


      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.


      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

      CompileCommand and backwards compatibility

      CompilerControl is supposed to replace CompileCommand in all use cases. CompileCommand will be kept for backwards compatibility and the goal is to keep the behaviour as much as possible.

      There are four layers of control that can be applied. Compiler Control will have the highest priority and override any other flag or command. Second is CompileCommand, third is any commandline flag, and fourth is the default flag value. If both Compiler control and CompileCommand are used, Compiler control will consider that CompileCommand is overriding the default value.

      The JVM should print a warning if both CompileCommand and compiler directives are used.

      Method patterns

      Compiler Control will use the same method pattern format as CompileCommand. The pattern consists of three parts package&class name, method name and signature. Any of these three may be wildcarded with a leading or trailing *. The default value of any part is *.



      Is composed by three parts

      java/example/Test + split + (Ljava/lang/String;)Ljava/lang/String;

      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.


      • Diagnostic command - Already in place
      • Working with full JDK - Already in place


      • Documentation: Flags and API
      • CCC: A CCC request will be required for directives format, JVM compiler flag changes and API.
      • Performance: Standard regression testing


        Issue Links



              neliasso Nils Eliasson (Inactive)
              neliasso Nils Eliasson (Inactive)
              Nils Eliasson Nils Eliasson (Inactive)
              Jesper Wilhelmsson
              Mikael Vidstedt
              0 Vote for this issue
              9 Start watching this issue