User Guide

Code Caching with BEA JRockit

Code caching is being introduced as an experimental feature in this version of BEA JRockit. In a future release of BEA JRockit, this feature is planned to be supported when used only with BEA WebLogic Server. For all other Java applications, it is provided "as-is" without any expressed or implied warranties or support by BEA Systems, Inc. and might contain errors and/or inaccuracies. Use of this feature with all other Java applications other than WebLogic Server is left solely to the discretion of the user without any endorsement from BEA Systems. Questions and problems may be reported via online BEA JRockit 1.4.2 newsgroups at http://newsgroups.bea.com.

Code caching—or code persistence—is the process of storing generated machine code to disk for retrieval when that code is required in a subsequent instance of the JVM. Since cached code is already generated, the time that code generation would require on subsequent startups is lessened and—usually—execution time is reduced. Persisting code should not be mistaken for hibernation, which means storing not only code but also objects and the entire heap.

This section describes how BEA JRockit's code caching feature works and shows you how to run it. It includes information on the following subjects:

Why Is Code Caching Helpful?

Startup time is a concern to many people, especially during development. For a typical run of the javac compiler, code generation in the JVM represents a majority of the startup time. By using code caching, startup time—and thus execution time—can be improved significantly.

What is the Cache?

The "cache" is a directory in your file system that stores previously generated code. The cache is shared among all instances of BEA JRockit that are started on the machine. The directory itself is comprised of a number of different files. The cache is logically divided into parts. Each part consists of a code file (with a .code file extension) and the index file (with a .ndx extension). Each part is numbered and the number is the same for the code and index file. Thus you will find pairs of files called, for example, 1.code and 1.ndx.

How to Use Code Caching

When BEA JRockit is started with code caching enabled, JIT-ed code is written to the cache. The next time you run BEA JRockit, it reads this file and instantiates any necessary cached methods as compiled code, rather than as bytecode that would require compilation.

This section describes how to use code caching by running these functions:

Enabling Code Caching

Enable code caching by using the -XXcodecache command line option with the appropriate arguments, as needed; for example:

-XXcodecache:[dir=directory],[readonly],[clobber]

Specifying a Cache Name

By default, the cached code is written to a per-user directory referred to as the "cache." The default locations are as follows (on windows the exact path name is different on different locales):

Windows:

C:\Documents and Settings\username>\Local Settings\Application Data\JRockit CodeCache\

Linux:

/tmp/<username>_jrockit_codecache/

To use a different cache directory, use the -XXcodecache:dir= command to specify the new cache name:

-XXcodecache:dir=/path/to/myCacheDirectory

For information on the cache directory, please refer to How Code Caching Works.

Code Caching in the Read/Write Mode

By default, code caching runs in read/write mode. This means that when BEA JRockit encounters a new method, it first checks the cache to see if a compiled version of the method is available in the cache. If so, that version is read into memory and used. If the method is not available from the cache, it is generated and then stored to cache.

Code Caching in the Read-only Mode

You can also instruct BEA JRockit to read the cache but not write newly compiled code to it. This is helpful, for example, when you have deployed your application in a production environment and want to ensure nothing changes in the working cache. Using readonly will prevent any updating. A typical command line invoking readonly might look like this:

-XXcodecache:file=myCacheFile,readonly

Other Code Caching Arguments

Table 6-1 list additional code caching arguments that you can use along with dir= and readonly.

Table 6-1 Other Code Caching Arguments

Argument	Description
`clobber`	Unconditionally overwrites code cache. This option is useful to force the recreation of a cache from scratch. Otherwise, by default the VM will attempt to append to an existing cache. This option is overridden by the `readonly` option.
exitonerror	Exit BEA JRockit when a code caching error occurs. By default BEA JRockit will recover from an error in the code cache by disabling the cache.

Using Code Caching to Improve Performance

The simplest way of using code caching to improve the startup time performance of an application is to run the application once to build an initial cache, then to rerun the same application; for example:

java -XXcodecache HelloWorld.

This will create the cache and add to that cache any compiled methods.

java -XXcodecache HelloWorld

This will use the previously created cache and thus run faster since no code will need to be compiled.

Setting the Verbosity Level

You can use the option -Xverbose:[codecache,codecache2] to set verbosity mode for status messages. codecache will print basic information about the cache as well as information about methods that could not be saved or loaded. Verbose level 2 (codecache2) will print more detailed messages about each method as it is being saved or loaded.

Enabling Code Caching by Using an Environment Variable

Instead of enabling code caching on each command line, you can set the environment variable JR_CODECACHE to enable code caching for all invocations of BEA JRockit. The value of the environment variable should be the same as the arguments to -XXcodecache. Since empty environment variables are not supported by all operating system, it is possible to set the variable to the value enable if all you want is the default options.

For example:

set JR_CODECACHE=enable
set JR_CODECACHE=ro,dir=/path/to/myCodeCache

How Code Caching Works

This section describes how code caching works. It includes descriptions of the following functionality:

What Happens When Code Caching Runs

When you start a Java program with code caching enabled, BEA JRockit access the cache directory and either opens an existing cache file or creates a new empty file. As new methods are generated, they are written to one of these files (if it is an existing file, the information is appended to the existing information). Finally, during shutdown, a new cache index is created and the cache directory is closed. If a fatal error occurred that would result in the creation of an invalid cache, the corrupted cache is automatically removed.

A code cache is not only application specific, but also application usage specific. This is because methods can be generated differently depending on class initialization order, static initializers, assertion status, and other conditions which may change if the application is run differently. Generally, as long as use of the application does not change significantly, these assumptions—which are checked when a method is loaded—will remain valid. If not, some of the methods stored in the cache will become invalid and will have to be regenerated. The newly generated methods are appended to the cache and override the previous definitions, which will still remain in the cache but are inaccessible.

Dealing with Code Changes

The codecache functionality will prevent cached code that is no longer valid from being used by the JVM. If changes are made to the class files after the code is stored to the cache, the code caching system prevents that stored code from being retrieved during subsequent runs. Many methods have dependencies to other classes and methods because of in-lining and other optimizations; these dependencies must also be stored and if they are no longer valid at retrieval time the stored method cannot be used.

To ensure that changed code is not retrieved, BEA JRockit stores classes based on the secure checksum (MD5 version) of the class bytes. This information is used as the index for a class when BEA JRockit looks up stored methods. Classes that have been changed are detected by a change in checksum, and any stored methods which depend on the old version of the class will be invalidated and will have to regenerated. A dependency check is run when loading a method to determine if the method has any dependencies on classes that have been invalidated.

Dealing with Cache Cleanup

This version of BEA JRockit has no provision for cleaning up the cache. It is therefore a good practice to occasionally delete the cache and recreate it by rerunning the application. This is also true if the application is being currently developed, in which case classes will be recompiled causing cached methods to be replaced. For more information, please refer to Cleaning Up the Cache.

Removing Obsolete Methods

Once the application development cycle has completed and the application usage has stabilized, it is probably a good idea to regenerate the cache to remove obsolete methods. Following that, the best way to deploy the application would be to run the application at install time and generate a cache, then subsequently run the application with this cache in read only mode as suggested previously. This will prevent new methods from being added to the cache, and allow the application cache to be shared.

Cache File Validity

The cache generated is very dependent on machine-specific factors as well as some JVM options. If any of these constraints are not satisfied when loading a cache, it is considered invalid. When the cache is invalid and you are running code caching in the read-only mode, the JVM code caching is disabled. If you are running it in the read/write mode, an attempt will be made to overwrite the cache. In this version of code caching, the file is dependent on machine architecture and operating system type.

Error Recovery

When code caching is enabled, BEA JRockit will always attempt to recover from a serious error specific to code caching. Examples of such errors are running out of memory, invalid code cache format, I/O errors while reading or writing from the cache. In these cases, the VM will continue running the application but code caching will be disabled and an error message will be displayed on the screen.

On the other hand, being unable to store or load an individual method because loading or saving constraints have changed is not considered an error and code caching will continue without saving or loading that particular method. If no verbosity is chosen, nothing will be reported. -Xverbose:codecache will result in messages about specific methods that could not be saved or loaded.

Cleaning Up the Cache

Currently, BEA JRockit does not perform any sort of cache cleanup. This means that any unused classes and methods will continue to persist in the cache even if they are never used again. This is helpful if you later decide to use a previous version of a class as it might still be in the cache. But to clean up a cache in this version of BEA JRockit, you will have to rebuild it when you have finished developing the application.