IBM User Guide for Java V7 on Windows > Performance > Class data sharing between JVMs

Class data sharing command-line options

Class data sharing and the cache management utilities are controlled using command-line options to the Java™ launcher.

For options that take a <size> parameter, suffix the number with "k" or "K" to indicate kilobytes, "m" or "M" to indicate megabytes, or "g" or "G" to indicate gigabytes.

-Xscmaxaot<size>

Sets the maximum number of bytes in the cache that can be used for AOT data. Use this option to ensure a certain amount of cache space is available for non-AOT data. By default, the maximum limit for AOT data is the amount of free space in the cache. The value of this option should not be smaller than the value of -Xscminaot and must not be larger than the value of -Xscmx.

-Xscmaxjitdata<x>

Optionally applies a maximum number of bytes in the class cache that can be used for JIT data. This option is useful if you want a certain amount of cache space guaranteed for non-JIT data. If this option is not specified, the maximum limit for JIT data is the amount of free space in the cache. The value of this option must not be smaller than the value of -Xscminjitdata, and must not be larger than the value of -Xscmx.

-Xscminaot<size>

Sets the minimum number of bytes in the cache to reserve for AOT data. By default, no space is reserved for AOT data, although AOT data is written to the cache until the cache is full or the -Xscmaxaot limit is reached. The value of this option must not exceed the value of -Xscmx or -Xscmaxaot. The value of -Xscminaot must always be considerably less than the total cache size because AOT data can be created only for cached classes. If the value of -Xscminaot is equal to the value of -Xscmx, no class data or AOT data is stored because AOT data must be associated with a class in the cache.

-Xscminjitdata<x>

Optionally applies a minimum number of bytes in the class cache to reserve for JIT data. If this option is not specified, no space is reserved for JIT data, although JIT data is still written to the cache until the cache is full or the -Xscmaxjit limit is reached. The value of this option must not exceed the value of -Xscmx or -Xscmaxjitdata. The value of -Xscminjitdata must always be considerably less than the total cache size, because JIT data can be created only for cached classes. If the value of -Xscminjitdata equals the value of -Xscmx, no class data or JIT data can be stored.

-Xscdmx<size>

You can use the -Xscdmx option to control the size of the class debug area when creating a shared class cache. The -Xscdmx option works in a similar way to the -Xscmx option used to control the overall size of the shared class cache. The size of -Xscdmx must not exceed the size of -Xscmx. By default, the size of the class debug area is a percentage of the free bytes in a newly created or empty cache.

size can be a percentage, expressed as a number, or an absolute value.

A class debug area is still created if you use the -Xnolinenumbers option with the -Xscdmx option on the command line.

-Xscmx<size>

Specifies cache size. This option applies only if a cache is being created and no cache of the same name exists. The default cache size is platform-dependent. You can find out the size value being used by adding -verbose:sizes as a command-line argument. The minimum cache size is 4 KB. The maximum cache size is also platform-dependent. (See Cache size limits.)

-Xshareclasses:<suboption>[,<suboption>...]

Enables class data sharing. Can take a number of suboptions, some of which are cache utilities. Cache utilities perform the required operation on the specified cache, without starting the VM. You can combine multiple suboptions, separated by commas, but the cache utilities are mutually exclusive. When running cache utilities, the message Could not create the Java virtual machine is expected. Cache utilities do not create the virtual machine.

Some cache utilities can work with caches from previous Java versions or caches created by JVMs with different bit-widths. These caches are referred to as "incompatible" caches.

You can use the following suboptions with the -Xshareclasses option:

help

Lists all the command-line suboptions.

name=<name>

Connects to a cache of a given name, creating the cache if it does not already exist. Also used to indicate the cache that is to be modified by cache utilities; for example, destroy. Use the listAllCaches utility to show which named caches are currently available. If you do not specify a name, the default name "sharedcc_%u" is used. %u in the cache name inserts the current user name.

cacheDir=<directory>

Sets the directory in which cache data is read and written. By default, <directory> is the user's C:\Documents and Settings\<username>\Local Settings\Application Data\javasharedresources directory. The user must have sufficient permissions in <directory>. The JVM writes persistent cache files directly into the directory specified. Persistent cache files can be safely moved and deleted from the file system. Non-persistent caches are stored in shared memory and have control files that describe the location of the memory. Control files are stored in a javasharedresources subdirectory of the cacheDir specified. Do not move or delete control files in this directory. The listAllCaches utility, the destroyAll utility, and the expire suboption work only in the scope of a given cacheDir.

enableBCI

Allows a JVMTI ClassFileLoadHook event to be triggered every time, for classes loaded from the cache. This mode also prevents caching of classes modified by JVMTI agents. For more information about this option, see Using the JVMTI ClassFileLoadHook with cached classes. This option is incompatible with the cacheRetransformed option. Using the two options together causes the JVM to end with an error message, unless -Xshareclasses:nonfatal is specified. In this case, the JVM continues without using shared classes.

This mode stores more data into the cache, and creates a Raw Class Data area by default. See the rcdSize= suboption. When using this suboption, the cache size might need to be increased with -Xscmx<size>.

A cache created without the enableBCI suboption cannot be reused with the enableBCI suboption. Attempting to do so causes the JVM to end with an error message, unless -Xshareclasses:nonfatal is specified. In this case, the JVM continues without using shared classes. A cache created with the enableBCI suboption can be reused without specifying this suboption. In this case, the JVM detects that the cache was created with the enableBCI suboption and uses the cache in this mode.

rcdSize=nnn

Controls the size of the Raw Class Data Area. The number of bytes passed to rcdSize must always be less than the total cache size. This value is always rounded down to the nearest multiple of the system page size. For example, these variations specify a Raw Class Data Area with a size of 1 MB:

-Xshareclasses:enableBCI,rcdSize=1048576
-Xshareclasses:enableBCI,rcdSize=1024k
-Xshareclasses:enableBCI,rcdSize=1m

If rcdSize is not used, and enableBCI is used, the JVM chooses a default Raw Class Data Area size.

If rcdSize is used, memory is reserved in the cache regardless of whether enableBCI is used.

If neither rcdSize or enableBCI is used, nothing is reserved in the cache for the Raw Class Data Area.

readonly

Opens an existing cache with read-only permissions. The JVM does not create a new cache with this suboption. Opening a cache read-only prevents the JVM from making any updates to the cache. It also allows the JVM to connect to caches created by other users or groups without requiring write access. By default, this suboption is not specified.

persistent (default)

Uses a persistent cache. The cache is created on disk, which persists beyond operating system restarts. Non-persistent and persistent caches can have the same name.

nonpersistent

Uses a non-persistent cache. The cache is deleted when the operating system shuts down. Non-persistent and persistent caches can have the same name. You must always use the nonpersistent suboption when running utilities such as destroy on a non-persistent cache.

verbose

Enables verbose output, which provides overall status on the shared class cache and more detailed error messages.

verboseAOT

Enables verbose output when compiled AOT code is being found or stored in the cache. AOT code is generated heuristically. You might not see any AOT code generated at all for a small application. You can disable AOT caching using the noaot suboption.

verboseIO

Gives detailed output on the cache I/O activity, listing information on classes being stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders must ask their parents for a class before they can load it themselves. It is usual to see many failed requests; this behavior is expected for the class loader hierarchy.

verboseHelper

Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your class loader.

silent

Turns off all shared classes messages, including error messages. Unrecoverable error messages, which prevent the JVM from initializing, are displayed.

nonfatal

Allows the JVM to start even if class data sharing fails. Normal behavior for the JVM is to refuse to start if class data sharing fails. If you select nonfatal and the shared classes cache fails to initialize, the JVM attempts to connect to the cache in read-only mode. If this attempt fails, the JVM starts without class data sharing.

none

Can be added to the end of a command line to disable class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption disables the shared class utility APIs. To disable class data sharing without disabling utility APIs, use the utilities suboption. For more information about the shared class utility APIs, see Obtaining information about shared caches.

utilities

Can be added to the end of a command line to disable class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption is like none, but does not disable the shared class utility APIs. For more information about the shared class utility APIs, see Obtaining information about shared caches.

modified=<modified context>

Used when a JVMTI agent is installed that might modify bytecode at run time. If you do not specify this suboption and a bytecode modification agent is installed, classes are safely shared with an extra performance cost. The <modified context> is a descriptor chosen by the user; for example, "myModification1". This option partitions the cache, so that only JVMs using context myModification1 can share the same classes. For instance, if you run HelloWorld with a modification context and then run it again with a different modification context, all classes are stored twice in the cache. See Runtime bytecode modification for more information.

reset

Causes a cache to be destroyed and then recreated when the JVM starts up. Can be added to the end of a command line as -Xshareclasses:reset.

destroy (Utility option)

Destroys a cache specified by the name, cacheDir, and nonpersistent suboptions. A cache can be destroyed only if all JVMs using it have shut down, and the user has sufficient permissions.

destroyAll (Utility option)

Tries to destroy all caches available using the specified cacheDir and nonpersistent suboptions. A cache can be destroyed only if all JVMs using it have shut down, and the user has sufficient permissions.

expire=<time in minutes>

Destroys all caches that have been unused for the time specified before loading shared classes. This option is not a utility option because it does not cause the JVM to exit. On NTFS file systems, the expire option is accurate to the nearest hour.

listAllCaches (Utility option)

Lists all the compatible and incompatible caches that exist in the specified cache directory. If you do not specify cacheDir, the default directory is used. Summary information, such as Java version and current usage is displayed for each cache.

printStats[=<data_types>] (Utility option)

Displays summary information for the cache specified by the name, cacheDir, and nonpersistent suboptions. The most useful information displayed is how full the cache is and how many classes it contains. Stale classes are classes that have been updated on the file system and which the cache has therefore marked "stale". Stale classes are not purged from the cache and can be reused.

Specify one or more data types, separated by a plus symbol (+), to additionally see more detailed information about that type of cache content. Data types include AOT data, class paths and ROMMethods. See printStats utility for more information.

printAllStats (Utility option)

Displays detailed information for the cache specified by the name, cacheDir, and nonpersistent suboptions. Every class is listed in chronological order, with a reference to the location from which it was loaded. AOT code for class methods is also listed.

See printAllStats utility for more information.

mprotect=[ all | default | none ]

By default, the memory pages containing the cache are protected at all times, unless a specific page is being updated. This protection helps prevent accidental or deliberate corruption to the cache. The cache header is not protected by default because this protection has a small performance cost. Specifying

all ensures that all the cache pages are protected, including the header. Specifying

none disables the page protection.

noBootclasspath

Prevents storage of classes loaded by the bootstrap class loader in the shared classes cache. Can be used with the SharedClassURLFilter API to control exactly which classes get cached. See Using the SharedClassHelper API for more information about shared class filtering.

cacheRetransformed

Enables caching of classes that have been transformed using the JVMTI RetransformClasses function.

noaot

Disables caching of AOT code. AOT code already in the shared data cache can be loaded.

nojitdata

Disables caching of JIT data. JIT data already in the shared data cache can be loaded.

-Xzero<options>

Enables reduction of the memory footprint of Java when concurrently running multiple Java invocations. -Xzero might not be appropriate for all types of applications because it changes the implementation of java.util.ZipFile, which might cause extra memory usage.

The <options> sharezip and sharebootzip apply to class data sharing. The option sharebootzip is enabled by default and can be disabled using -Xzero:nosharebootzip. For further details on -Xzero and the options available, see JVM command-line options.

Parent: Class data sharing between JVMs

Error 404 - Not Found

The document you are looking for may have been removed or re-named. Please contact the web site owner for further assistance.