cl4cds

cl4cds (https://github.com/simonis/cl4cds) is a little tool which helps exploring the new Application Class Data Sharing (AppCDS) feature in OpenJDK 10. AppCDS allows sharing of application classes even if they get loaded by a custom class loaders, but unfortunately there’s currently no default tooling available to make this feature accessible to end users. That’s where cl4cds (which is an acronym for "class list for class data sharing") kicks in. It converts a class list obtained from running your application with -Xlog:class+load=debug to a format which can be passed to the VM as a parameter of the -XX:SharedClassListFile= option. This article documents the cl4cds tool but at the same time also describes the implementation and the benefits of the ovarall CDS/AppCDS features.

TL;DR

If you’re only interested in the cl4cds utility, you can use it as follows (tested with OpenJDK 10 and Tomcat 9):

$ export JAVA_HOME=JAVA_10_HOME # (1)
$ export CATALINA_OPTS=-Xlog:class+load=debug:file=/tmp/tomcat.classtrace # (2)
$ CATALINA_HOME/bin/catalina.sh start // (3)
$ CATALINA_HOME/bin/catalina.sh stop // (4)
$ JAVA_10_HOME/bin/java io.simonis.cl4cds /tmp/tomcat.classtrace /tmp/tomcat.cls
$ export CATALINA_OPTS="-Xshare:dump -XX:+UseAppCDS -XX:SharedClassListFile=/tmp/tomcat.cls -XX:+UnlockDiagnosticVMOptions -XX:SharedArchiveFile=/tmp/tomcat.jsa" (5)
$ CATALINA_HOME/bin/catalina.sh start (6)
$ export CATALINA_OPTS="-Xshare:on -XX:+UseAppCDS -XX:+UnlockDiagnosticVMOptions -XX:SharedArchiveFile=/tmp/tomcat.jsa" (7)
$ CATALINA_HOME/bin/catalina.sh start (8)

1. AppCDS only works with OpenJDK 10 and higher

2. Trace all the classes which get loaded into the file /tmp/tomcat.classtrace

3. Start Tomcat and run your application

4. Stop Tomcat

5. Set the options for creating a shared class archive in /tmp/tomcat.jsa (-XX:SharedArchiveFile is a diagnostic option so we have to enable it first by using -XX:+UnlockDiagnosticVMOptions)

6. Restart Tomcat to dump the shared class archive

7. Set the options for using the shared class archive from /tmp/tomcat.jsa

8. From now on, Tomcat will load available classes (both, system and application ones) from the shared archive if available.

The current cl4cds command line options are as follows:

io.simonis.cl4cds [<class-trace-file> [<class-list-file>]]

  <class-trace-file>: class trace obtained by running -Xlog:class+load=debug
                      if not specified read from <stdin>
  <class-list-file> : class list which can be passed to -XX:SharedClassListFile
                      if not specified written to <stdout>

  The following properties can be used to configure cl4cds:
    -Dio.simonis.cl4cds.debug=true :
       Print additional tracig to <stderr> (defaults to 'false')
    -Dio.simonis.cl4cds.dumpFromClassFile=true :
       Include classes into the output which are loaded from plain classfiles.
       This is currently not supported by OpenJDK 10 which can only dump
       classes from .jar files but may change eventually (defaults to 'false')

If you’re interested in the implementation details of CDS/AppCDS, their current limitations and their performance and memory characteristics please read on the extended version of this article at https://simonis.github.io/cl4cds or watch my talk about Class Data Sharing (mp4, WebM/VP9, YouTube) in the Free Java DevRoom at FOSDEM 2018.

Colophon

Rendered with AsciiDoctor version 2.0.22