Writing Directives

Options are instructions for compilation. Options provide method-context precision. Available options vary by compiler and require specific types of values.

Individual compiler directives are written in a directives file. Only directive files, not individual directives, can be added to the stack of active directives.

1. Create a file with a .json extension. Directive files are written using a subset of JSON syntax with minor additions and deviations.
2. Insert the following syntax as a template you can work from:

   [  //Array of Directives
       {   //Directive Block
           //Directive 1
       },
       {   //Directive Block
           //Directive 2
       },
   ]
   

   The components of this template are:

   Array of Directives:

   • A directives file stores an array of directive blocks, denoted with a pair of brackets ([]).

   • The brackets are optional if the file contains only a single directive block.

   Directive Block:

   • A block is denoted with a pair of braces ({}).

   • A block contains one individual directive.

   • A file can contain any number of directive blocks.

   • Blocks are separated with a comma (,).

   • A comma is optional following the final block in the array.

   Individual Directive:

   • Each individual directive must exist within a directive block.

   • Files can contain multiple directives when they contain multiple directive blocks.

   Comments:

   • Single-line comments are inserted with two slashes (//).

   • Multiline comments are not allowed.

3. Add or remove directive blocks from the template to match the number of directives you want in the file.
4. Fill in each directive block with one compiler directive. See Writing a Compiler Directive.
5. Reorder the directive blocks if necessary. The ordering of directives within a file is significant. Directives written closer to the beginning of the array receive higher priority. For more information, see How Are Directives Ordered in the Directives Stack? and How Are Directives Applied to Code?

[  //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,
        },
    },
]

Compiler directives must be written within a directives file. Repeat these steps for each individual compiler directive you want to write in a directives file.

1. Insert the following block of code, as a template you can work from, to write an individual compiler directive. This block of code is a directive block.

       {
           match: [],
           c1: {
               //c1 directive options
           },
           c2: {
               //c2 directive options
           },
           //Directive options applicable to all compilers
       },
   

2. Provide the match attribute with an array of method patterns. See Writing a Method Pattern in a Compiler Directive.
   For example:

           match: ["java*.*", "oracle*.*"],
   

3. Provide the c1 attribute with a block of comma-separated directive options. Ensure that these options are valid for the c1 compiler.
   For example:

           c1: {
               Enable: true,
               Exclude: true,
               BreakAtExecute: true,
           },
   

4. Provide the c2 attribute with a block of comma-separated directive options. This block can contain a mix of common and c2 exclusive compiler options.
   For example:

           c2: {
               Enable: false,
               MaxNodeLimit: 1000,
           },
   

5. Provide, at the end of the directive, options you want applicable to all compilers. These options are considered written within the scope of the common block. Options are comma-separated.
   For example:

           BreakAtCompile: true,
           DumpReplay: true,
   

6. Clean up the file:
   1. Check the ordering and potential duplication of directive options. If there is a conflict, then the last occurrence of an option takes priority. Conflicts most likely occur between the common block and the c1 or c2 blocks, not between c1 and c2 blocks.
   2. Avoid writing c2–exclusive directive options in the common block. Although the common block can accept a mix of common and c2–exclusive options, it’s misleading to structure a directive this way because c2–exclusive options in the common block have no effect on the c1 compiler. Write c2–exclusive options within the c2 block instead.
   3. If either the c1 or c2 attribute has no corresponding directive options, then omit the attribute-value syntax for that compiler.

    {
        match: ["java*.*", "oracle*.*"],
        c1: {
            Enable: true,
            Exclude: true,
            BreakAtExecute: true,
        },
        c2: {
            Enable: false,
            MaxNodeLimit: 1000,
        },
        BreakAtCompile: true,
        DumpReplay: true,
    },

    {
       "match": "*Concurrent.*",
        c2: {
            "Exclude": true,
        }
    },

A ccstr is a method pattern. It can be written precisely or generalized with wildcard characters. It specifies what best-matching Java code should have accompanying directive options applied, or what Java code should be inlined.

1. Fill in the following syntax to format your method pattern: package/class.method(parameter_list). If you’re unable to be precise, see Step 2 for ways to generalize a method pattern with wildcard characters.
   An example method pattern that uses this style of formatting is:

   java/lang/String.indexOf()
   

   Other formatting styles are available. This ensures backward compatibility with earlier ways of method matching such as CompileCommand. Valid formatting alternatives for the previous example include:

   • java/lang/String.indexOf()
   • java/lang/String,indexOf()
   • java/lang/String indexOf()
   • java.lang.String::indexOf()

   You may find the last formatting style preferable because it matches the Hotspot output.
2. Insert a wildcard character (*) where you need to generalize part of the method pattern.
   The following are valid generalizations of the method pattern example from Step 1:

   • java/lang/String.indexOf*
   • *lang/String.indexOf*
   • *va/lang*.*dex*
   • java/lang/String.*
   • *.*
   Increased generalization leads to decreased precision in these examples. This is risky because more Java code becomes a potential match with the method pattern. Therefore, it’s important to use the wildcard character (*) judiciously.
3. Modify the signature portion of the method pattern. Signatures are written according to the Java Specifications. Signature matches must be exact, otherwise a signature defaults to a wildcard character (*). Omitted signatures also default to a wildcard character. Signatures themselves cannot contain the wildcard character.
4. Optional: If you’re writing a method pattern to accompany the inline directive option, then there are additional characters you must prefix the method pattern with. See 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.

1. Write inline: in the common block, c1, or c2 block of a directive.
2. Accompany this with 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.
3. Prefix a + to force inlining of any matching Java code.
4. Prefix a - to prevent inlining of any matching Java code.
5. Optional: If you need inlining behavior applied to multiple method patterns, then repeat these steps to write multiple inline statements. Don’t write a single array that contains all patterns.

The Enable option hides aspects of directives. This option prevents duplication between directives.

[
    {
        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,
        },
    },
]

[
    {
        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
        },
    },
]