Java Virtual Machine Options

This document describes the less common and nonstandard VM options that are specific to Apple. All standard Java HotSpot VM options are available with the OS X Java VM. Information on the standard HotSpot VM options can be found in the java man page. In addition to the standard options, many nonstandard (-X and -XX) options are available. Some of the more common nonstandard options are omitted here, but can be viewed by passing the -X option to java.

A Note About Values

Except where noted, when bytes are specified as a parameter in an option, you may also designate kilobytes, megabytes, or gigabytes with the letters k, m, and g, respectively. You may use either uppercase or lowercase letters. For example, the following are all equivalent values: 4194304, 4096k, 4096K, 4m, and 4M.

General Options

-server

This option selects the HotSpot Server VM.

-X

Displays a brief description of the most common nonstandard VM options.

-Xfuture

Performs strict format-checking of class files. This option enforces a tighter conformance to the class file specification than the default, which is based on the standard in Java 1.1.x. You should test your code with this flag to ensure functionality in future versions of Java that may enforce stricter class file format-checking.

-Xrs

Same as -XX:+ReduceSignalUsage.

-XX:- MaxFDLimit

Directs the VM to refrain from setting the file descriptor limit to the default maximum. The default behavior is to set the limit to the value specified by OPEN_MAX, which is 10240. Normally, this is the maximum number of files that a process may have open. It is possible, however, to increase this limit to a user-specified value with the sysctl utility. Under such circumstances, you may want to pass -XX:-MaxFDLimit to stop the Java VM from restricting the number of open files to 10240.

-XX:MaxDirectMemorySize=size in megabytes

The maximum memory that can be allocated using NIO direct buffers. The default is 64 (64M).

-XX:+ReduceSignalUsage

Directs the VM to ignore SIGHUP, SIGINT, and SIGTERM signals. You need to implement handlers for these signals in native code as appropriate. Also, implement any relevant shutdown procedure from System.exit.

-XX:ReservedCodeCacheSize=size in bytes

Sets the maximum code cache size. The default value is 32M for the client compiler and 48M for the server compiler.

-XX:+UseLargePages

Tells the HotSpot VM to allocate the Java heap using large (2 MB) pages instead of default (4 KB) pages. This allocated memory is wired memory, and therefore the requested amount must be available as free physical memory. This option is available in OS X v10.6 and later on machines running the 64-bit OS X kernel. Additional information about this option can be found at the Java Hotspot VM Options site.

-XX:+ExitOnLargePageFailure

Tells the HotSpot VM to exit if large page support is not enabled or available.

OS X Specific

-Xdock:icon=pathToIconFile

Sets the icon displayed in the Dock. By default, OS X displays a generic Java icon unless you specify otherwise. You only need to use this for applications launched from the command line or from a JAR file. Double-clickable application bundles designate their icon in the Info.plist file.

-Xdock:name=applicationName

Sets the name to display in the Dock and in the menu bar. By default, OS X displays the fully qualified name of the main class unless you specify otherwise. You need to use this only for applications launched from the command line or from a JAR file. Double-clickable application bundles get the appropriate name from the Info.plist file.

-XX:+UseFileLocking

Off by default, this option enables Carbon file locking. If your Java application will be interacting with files that may be simultaneously acted on by Carbon applications, use this option. It keeps the respective applications from modifying the file while the other is accessing it.

Garbage Collection: Memory Usage

-XX:MinHeapFreeRatio=percentage as a whole number

Modifies the minimum percentage of the heap kept free after garbage collection. The default value of 40. If at least 40% of the heap is not freed after garbage collection, the heap size increases.

-XX:MaxHeapFreeRatio=percentage as a whole number

Changes the maximum percentage of heap kept free after garbage collection before the heap is shrunk. The default value is 70. This means that if a garbage collection results in more than 70% of the heap being freed, the heap size decreases.

-XX:NewSize=size in bytes

Sets the default size for the Eden generation of allocated objects. The default value is 640K. (The -server flag increases the default size to 2M.)

-XX:MaxNewSize=size in bytes

Allows you to change the upper limit of the young object space in which new objects are allocated. The default value is 640K. (The -server flag increases the default size to 2M.)

-XX:NewRatio=value

Changes the ratio of new to old space sizes from the default value of 8 where the new space is 1/8 the size of the old space.

-XX:SurvivorRatio=number

Modifies the ratio of size of the Eden to the survivor space from the default of 10 where Eden is survivorRatio+2 times larger than the survivor space.

-XX:TargetSurvivorRatio=percentage

Desired percentage of survivor space used after scavenge. Default is 50.

-XX:MaxPermSize=size in MB

Modifies the size of the permanent generation. The default is value is 32 (32MB).

Garbage Collection: General Settings

-Xincgc

This flag indicates that the VM should use concurrent mark and sweep garbage collection in incremental mode. It is equivalent to -XX:+UseConcMarkSweepGC -XX:+CMSIncrementalMode.

-XX:+UseConcMarkSweepGC

Enables concurrent mark and sweep garbage collection. This option has an effect only on multiprocessor computers.

-XX:+UseParallelGC

Enables parallel garbage collection. This option has an effect only on multiprocessor computers.

-XX:-DisableExplicitGC

Ignores explicit calls to the System.gc method in your code. The VM still performs garbage collection when it normally would. This option just disallows you from explicitly forcing garbage collection in your code.

-XX:+PrintTenuringDistribution

Prints tenuring age information for allocated objects in the young generation.

Compilation

-XX:CompileThreshold=value

Changes the number of method invocations (branches) before compilation begins. The default is 1500.

-XX:+CITime

Displays how much time is spent in compiled code.

-XX:+PrintCompilation

Prints a trace of the methods as they are compiled.

Threading

-XX:NewSizeThreadIncrease=size in KB

Specifies how much to increment the young object space size per active thread. This option may be useful in regulating an increased allocation rate due to increased threads. The default increment is 16 (16 kilobytes).

-XX:ThreadStackSize=size in KB

Changes the thread stack size from the operating system’s default size.

-XX:+UseTLAB

Enables a thread-local allocation buffer so that heavily threaded applications can be allocated more efficiently, greatly increasing allocation performance. For Java 1.4.2, this option is on by default on multiprocessor computers and in OS X Server. For J2SE 5.0, it is on for all configurations.