Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8221706

Implement Dynamic CDS Archive

    Details

    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      The existing AppCDS should continue to function.
    • Interface Kind:
      add/remove/modify command line option
    • Scope:
      JDK

      Description

      Summary

      Support dynamic archiving at application runtime when enabled by command line option. The user can then use the dynamic archive in subsequent application run by using an existing command line option.

      Problem

      With the existing application class-data sharing (AppCDS) feature, the user needs to generate a classlist and then using the classlist to generate a shared archive. Dynamic CDS archive enhances the usability of AppCDS by eliminating the classlist generation step.

      Solution

      To create a dynamic CDS archive, the user can just run the java application with the following vm option: -XX:ArchiveClassesAtExit=<archive name>

      To run the same application using the dynamic CDS archive, the user can make use of the existing -XX:SharedArchiveFile=<archive name> vm option.

      Specification

      To create a dynamic CDS archive:

      java -XX:ArchiveClassesAtExit=<dynamic archive> -cp <app jar> MyApp

      The above command creates a dynamic CDS archive with the default CDS archive as the base archive. If the default CDS archive does not exist. VM will exit with the following error:

      ArchiveClassesAtExit not supported when base CDS archive is not loaded

      The user could also create a dynamic CDS archive with a specific base archive as follows:

      java -XX:SharedArchiveFile=<base archive> -XX:ArchiveClassesAtExit=<dynamic archive> -cp <app jar> MyApp

      Error checks:

      • -Xshare:dump specified with -XX:ArchiveClassesAtExit will result in the following VM error:
      Error occurred during initialization of VM
        -XX:ArchiveClassesAtExit cannot be used with -Xshare:dump
      • more than one base archive in the -XX:SharedArchiveFile will result in the following VM error:
      Error occurred during initialization of VM
        Cannot have more than 1 archive file specified in -XX:SharedArchiveFile during CDS dumping
      • same archive file specified in -XX:SharedArchiveFile and -XX:ArchiveClassesAtExit will result in the following VM error:
      Error occurred during initialization of VM
        Cannot have the same archive file specified for -XX:SharedArchiveFile and -XX:ArchiveClassesAtExit:<archive name>
      • If the base archive does not exist, VM will exit with an error.

      If the base archive contains additional path component besides the runtime image and the classpath (-cp), dynamic archive dumping is disabled. Specifically, if the base archive has appended boot classpath, VM will issue the following warning:

      Dynamic archiving is disabled because base layer archive has appended boot classpath

      If the base archive has module path, VM will issue the following warning:

      Dynamic archiving is disabled because base layer archive has module path

      To run the application using the dynamic CDS archive and the default CDS (base) archive:

      java -XX:SharedArchiveFile=<dynamic archive> -cp <app jar> MyApp

      The above command doesn't specify a base archive. The base archive info, including its name and full path, will be retrieved from the dynamic archive header.

      Note that the user could also use the -XX:SharedArchiveFile option for specifying a regular (non-dynamic) CDS archive. Therefore, the specified archive in the -XX:SharedArchiveFile option could be of a regular or a dynamic type. During VM starts up, the specified archive header will be read. If it is of dynamic archive type, the base archive location will be retrieved from the header. It also checks if the default CDS archive flag is set in the header. If the flag is set, it will then obtain the default CDS archive location based on the current run time environment. This is to account for if the default CDS archive file has been moved to a different location after the creation of the dynamic archive. If it is of the regular archive type, then it will work as before as in the existing AppCDS case when the archive is specified at a location.

      To run the application using the dynamic CDS archive and a specific base CDS archive:

      java -XX:SharedArchiveFile=<base archive>:<dynamic archive> -cp <app jar> MyApp

      The above command is useful if the base archive used for creating the dynamic archive has been moved. Normally, just specifying the dynamic archive should be sufficient since the base archive info can be retrieved from the dynamic archive header.

      Error checks:

      • if base archive is specified in the dynamic archive location, VM will issue the following error:
      Error occurred during initialization of VM       
        Not a base shared archive:<archive name>
      • if dynamic archive is specified in the dynamic archive location, VM will issue the following error:
      Error occurred during initialization of VM       
        Not a top shared archive:<archive name>
      • if base archive not specified, i.e. -XX:SharedArchiveFile=:<dynamic archive>, VM will issue the following error:
      Error occurred during initialization of VM       
        Base archive was not specified:<archive name>
      • if dynamic archive not specified, i.e. -XX:SharedArchiveFile=<base archive>:, VM will issue the following error:
      Error occurred during initialization of VM       
        Top archive was not specified:<archive name>
      • if more than 2 archive files are specified, VM will issue the following error:
      Error occurred during initialization of VM       
        Cannot have more than 2 archive files specified in the -XX:SharedArchiveFile option

      If the content of the specified base archive is different from the one used during dynamic archive dump time, VM will report errors such as CRC checksum mismatch.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                ccheung Calvin Cheung
                Reporter:
                jiangli Jiangli Zhou
                Reviewed By:
                Ioi Lam, Karen Kinnear (Inactive)
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: