Summary
-------

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

Goals
-----

  - 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

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:

- 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 
                 PrintAssembly:true,  
            },
            // 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
                 Exclude:true,    
            }    
            // 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).

### 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:CompilerDirectivesFile=<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


### 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 *. 

Example: 

    java/example/Test.split

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.



Dependences
-----------

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


Impact
------

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