Class data sharing

Sharing class data between JVMs improves start up performance and reduces memory footprint.

Start up performance is improved by placing classes that an application needs when initializing into a shared classes cache. The next time the application runs, it takes much less time to start because the classes are already available. When you enable class data sharing, AOT compilation is also enabled by default, which dynamically compiles certain methods into AOT code at runtime. By using these features in combination, startup performance can be improved even further because the cached AOT code can be used to quickly enable native code performance for subsequent runs of your application.

When class data sharing is enabled, OpenJ9 automatically creates a memory mapped file that stores and shares the classes in memory.

The shared classes cache is updated dynamically; When an application loads new classes, the JVM automatically stores them in the cache without any user intervention.

Memory footprint is reduced by sharing common classes between applications that run in separate Java VMs.

Enabling class data sharing

Class data sharing is enabled by default for bootstrap classes only (the equivalent of specifying -Xshareclasses:bootClassesOnly,nonFatal,silent), unless your application is running in a container. If you want to change the default behaviour, use the -Xshareclasses option on the command line. For example:

  • You can change the name and location of the default shared classes cache.
  • You can enable messages about the default shared classes cache by using the default command line option without the silent suboption: -Xshareclasses:bootClassesOnly,nonFatal.

Note: If you have multiple VMs and you do not change the default shared classes behavior, the VMs will share a single default cache, assuming that the VMs are from a single Java installation. If the VMs are from different Java installations, the cache might be deleted and recreated; for more information, see the following section about best practices.

You can treat the default cache like any other shared classes cache, for example you can print statistics for it, change the soft maximum limit size, or delete it.

You can enable class data sharing for non-bootstrap classes as well, by using -Xshareclasses without the bootClassesOnly suboption. You can also disable all class data sharing by using the none suboption.

Best practices for using -Xshareclasses

The -Xshareclasses option is highly configurable, allowing you to specify where to create the cache, how much space to allocate for AOT code and more. You can also set the cache size by using the -Xscmx option. When shared classes is enabled, it is good practice to specify some of the cache behavior:

  • Set an application-specific cache name (-Xshareclasses:name=<name>).

    If a cache with the specified name doesn't already exist, a new cache is created.

    This avoids sharing your application cache with a cache that is enabled by default or with another application that doesn't set a name, and ensures that the size of your application cache can be set appropriately and that cache space is used exclusively for your application.

    Note: You cannot change the size of a default cache that already exists by using the -Xscmx option, as that option has no effect on a pre-existing cache.

  • Set a specific cache directory (-Xshareclasses:cacheDir=<directory>).

    Set a cache directory that is specific to your application, to avoid sharing the default cache directory with the default cache, or other application caches that don't set a cache directory. Your application will be unaffected by a user running java -Xshareclasses:destroyAll.

    In addition, if you have VMs from different Java installations, of the same Java release and installed by the same user, each VM checks whether the existing default shared cache in the cache directory is from the same Java installation as the VM. If not, the VM deletes that shared cache, then creates a new one. Specifying a different cache directory for each Java installation avoids this situation.

  • Ensure that the cache directory permissions are set appropriately (-Xshareclasses:cacheDirPerm).

    It is good practice to explicitly set permissions for the cache directory when the defaults are not appropriate.

  • Set the -Xshareclasses:nonfatal option.

    This option means that your application can start even if there is a problem opening or creating the shared cache, in which case, the VM might be able to start without class data sharing.

Support for custom class loaders

Classes are shared by the bootstrap class loader internally in the OpenJ9 VM. If you are using a custom class loader, you can use the Java Helper API to find and store classes in the shared classes cache.

For more information, see Using the Java Helper API.

Cache utilities

Several utilities are provided for managing active caches, which are invoked by specifying -Xshareclasses suboptions. These utilities control the following types of operations:

  • Adjust the minimum and maximum amount of cache space reserved for AOT or JIT data.
  • Adjust the soft maximum size of the cache.
  • Create snapshots of a cache.
  • Create a cache from a snapshot.
  • Remove caches and cache snapshots.
  • List all the compatible and incompatible caches and snapshots.
  • For problem determination, invalidate and revalidate AOT methods that cause a failure in an application.
  • For problem determination, provide information to analyze the contents of a shared classes cache.

For more information, see -Xshareclasses.

See also