Commands for Working with Directive Files

This topic examines commands and the effects of working with completed directive files.

Compiler Directives and the Command Line

You can use the command-line interface to add and print compiler directives while starting a program.

You can specify only one directives file at the command line. All directives within that file are added to the directives stack and are immediately active when the program starts. Adding directives at the command line enables you to test the performance effects of directives during a program’s early stages. You can also focus on debugging and developing your program.

Adding Directives Through the Command Line

The following command-line option specifies a directives file:
XX:CompilerDirectivesFile=file
Include this command-line option when you start a Java program. The following example shows this option, which starts TestProgram:
java -XX:+UnlockDiagnosticVMOptions -XX:CompilerDirectivesFile=File_A.json TestProgram
In the example:
  • -XX:+UnlockDiagnosticVMOptions enables diagnostic options. You must enter this before you add directives at the command line.

  • -XX:CompilerDirectivesFile is a type of diagnostic option. You can use it to specify one directives file to add to the directives stack.

  • File_A.json is a directives file. The file can contain multiple directives, all of which are added to the stack of active directives when the program starts.

  • If File_A.json contains syntax errors or malformed directives, then an error message is displayed and TestProgram does not start.

Printing Directives Through the Command Line

You can automatically print the directives stack when a program starts or when additional directives are added through diagnostic commands. The following command-line option to enables this behavior:
-XX:+CompilerDirectivesPrint
The following example shows how to include this diagnostic command at the command line:
java -XX:+UnlockDiagnosticVMOptions -XX:+CompilerDirectivesPrint -XX:CompilerDirectivesFile=File_A.json TestProgram 

Compiler Directives and Diagnostic Commands

You can use diagnostic commands to manage which directives are active at runtime. You can add or remove directives without restarting a running program.

Crafting a single perfect directives file might take some iteration and experimentation. Diagnostic commands provide powerful mechanisms for testing different configurations of directives in the directives stack. Diagnostic commands let you add or remove directives without restarting a running program’s JVM.

Getting Your Java Process Identification Number

To test directives you must find the processor identifier (PID) number of your running program.

  1. Open a terminal.
  2. Enter the jcmd command.
The jcmd command returns a list of the Java process that are running, along with their PID numbers. In the following example, the information returned about TestProgram :
11084 TestProgram

Adding Directives Through Diagnostic Commands

You can add all directives in a file to the directives stack through the following diagnostic command.

Syntax:
jcmd pid Compiler.directives_add file
The following example shows a diagnostic command:
jcmd 11084 Compiler.directives_add File_B.json
The terminal reports the number of individual directives added. If the directives file contains syntax errors or malformed directives, then an error message is displayed, and no directives from the file are added to the stack, and no changes are made to the running program.

Removing Directives Through Diagnostic Commands

You can remove directives by using diagnostic commands.

To remove the top-most, individual directive from the directive stack, enter:
jcmd pid Compiler.directives_remove
To clear every directive you added to the directives stack, enter:
jcmd pid Compiler.directives_clear
It’s not possible to specify an entire file of directives to remove, nor is any other way available to remove directives in bulk.

Printing Directives Through Diagnostic Commands

You can use diagnostic commands to print the directives stack of a running program.

To print a detailed description of the full directives stack, enter:
jcmd pid Compiler.directives_print
Example output is shown in What Is the Default Directive?

How Directives Are Ordered in the Directives Stack?

The order of the directives in a directives file, and in the directives is very important. The top-most, best-matching directive in the stack receives priority and is applied to code compilation.

The following examples illustrate the order of directive files in an example directives stack. The directive files in the examples contain the following directives :

  • File_A contains Directive 1 and Directive 2.

  • File_B contains Directive 3.

  • File_C contains Directive 4 and Directive 5.

Starting an Application With or Without Directives

You can start the TestProgram without specifying the directive files.
  • To start TestProgram without adding any directives, at the command line, enter the following command:
    java TestProgram
  • TestProgram starts without any directives file specified.

  • The default directive is always the bottom-most directive in the directives stack. Figure 2-1 shows the default directive as Directive 0. When you don’t specify a directives file, the default directive is also the top-most directive and it receives priority.

Figure 2-1 Starting a Program Without Directives

Description of Figure 2-1 follows
Description of "Figure 2-1 Starting a Program Without Directives"
You can start an application and specify directives.
  • To start the TestProgram application and add the directives from File_A.json to the directives stack, at the command line, enter the following command:
    java -XX:+UnlockDiagnosticVMOptions -XX:CompilerDirectivesFile=File_A.json TestProgram
  • TestProgram starts and the directives in File_A are added to the stack. The top-most directive in the directives file becomes the top-most directive in the directives stack.

  • Figure 2-2 shows that the order of directives in the stack, from top to bottom, becomes is [1, 2, 0].

Figure 2-2 Starting a Program with Directives

Description of Figure 2-2 follows
Description of "Figure 2-2 Starting a Program with Directives"

Adding Directives to a Running Application

You can add directives to a running application through diagnostic commands.
  • To to add all directives from File_B to the directives stack, enter the following command:
    jcmd 11084 Compiler.directives_add File_B.json

    The directive in File_B is added to the top of the stack.

  • Figure 2-3 shows that the order of directives in the stack becomes is [3, 1, 2, 0].

Figure 2-3 Adding a Directive to a Running Program

Description of Figure 2-3 follows
Description of "Figure 2-3 Adding a Directive to a Running Program"
You can add directive files through diagnostic commands to the TestProgram while it is running:
  • To add all directives from File_C to the directives stack, enter the following command.
    jcmd 11084 Compiler.directives_add File_C.json
  • Figure 2-4 shows that the order of directives in the stack becomes is [4, 5, 3, 1, 2, 0].

Figure 2-4 Adding multiple Directives to a Running Program

Description of Figure 2-4 follows
Description of "Figure 2-4 Adding multiple Directives to a Running Program"

Removing Directives from the Directives Stack

You can remove the top-most directive from the directive stacks through diagnostic commands.
  • To remove Directive 4 from the stack, enter the following command:
    jcmd 11084 Compiler.directives_remove
  • To remove more, repeat this diagnostic command until only the default directive remains. You can’t remove the default directive.

  • Figure 2-5 shows that the order of directives in the stack becomes is [5, 3, 1, 2, 0].

Figure 2-5 Removing One Directive from the Stack

Description of Figure 2-5 follows
Description of "Figure 2-5 Removing One Directive from the Stack"
You can remove multiple directives from the directives stack.
  • To clear the directives stack, enter the following command:
    jcmd 11084 Compiler.directives_clear
  • All directives are removed except the default directive. You can’t remove the default directive.

  • Figure 2-6 shows that only Directive 0 remains in the stack.

Figure 2-6 Removing All Directives from the Stack

Description of Figure 2-6 follows
Description of "Figure 2-6 Removing All Directives from the Stack"