Bug ID: JDK-8272331 Automatically generate the CDS archive if necessary

Type: CSR
Component: hotspot
Sub-Component: runtime

Priority: P4
Status: Closed
Resolution: Approved
Fix Versions: 18

Submitted: 2021-08-11
Updated: 2022-01-07
Resolved: 2021-09-20

Summary
-----------------
Today we must explicitly generate a CDS archive in a separate "dumping" step. Also, if the application or the JDK is updated, the CDS archive needs to be manually updated. To improve usability, we should allow the CDS archive to be automatically generated or updated.

Solution
--------------------
Introduce a VM option, -XX:+AutoCreateSharedArchive. When this flag is enabled for running with a dynamic shared archive, if the archive file is non-existent, out-of-date or damaged, we automatically generate or update the shared archive at VM exit. This flag must be used with -XX:SharedArchiveFile=`<archive_name>`.

Specification
---------------------

```
java -XX:+AutoCreateSharedArchive -XX:SharedArchiveFile=<file> ....
```

 - The default value of `AutoCreateSharedArchive` is false.
 - `-XX:+AutoCreateSharedArchive` may be used only with `-Xshare:auto`. It cannot be used with `-Xshare:on`.
 - If `AutoCreateSharedArchive` is true, `SharedArchiveFile` must be specified, or else the VM will exit with an error message.
 - If `AutoCreateSharedArchive` is true, and the CDS archive `<file>` can be successfully loaded, the VM will use the archive without regenerating it.
 - Otherwise: the VM takes the actions described in the following section.
   - If `<file>` doesn't exist, it will be created
   - If `<file>` exists, it will be regenerated if:
     - it is a valid dynamic archive file that was generated by JDK 18 or later, and
     - it is out of date (because the JDK or the application has been updated)
   - Otherwise, we have a damaged archive, a system error, or a user error. We should warn the user and do not update the archive. The application will be executed without loading `<file>`.

NOTE: the following is NOT part of the CSR specification. I wanted to describe the exact runtime behavior so that tests can be written for it. For readability, I need to use rich text, but you can't use rich text in the main bug (JDK-8261455), so I'll put it here. (This entry will be edited per discussion). ----- Error Handling Specification ``` -XX:SharedArchiveFile can be specified in two styles: (A) The base archive is not specified: -XX:SharedArchiveFile=<file> (B) [TBD] The base archive is specified: -XX:SharedArchiveFile=<base>:<file> Case (A) <file> doesn't exist 1: If the JDK's default CDS archive cannot be loaded 1.1 Print a warning. 1.2 Continue execution without using any CDS archive. <file> will not be generated. 2: Otherwise, at VM exit, <file> will be created as a dynamic archive based on the current loaded base archive. <file> exists: 3: CDSFileMapHeaderBase._magic cannot be read, or is not CDS_DYNAMIC_ARCHIVE_MAGIC: 3.1 If <file> is a static archive, the VM will print a warning and ignore the -XX:+AutoCreateSharedArchive flag. It will continue execution and attempt to load <file> as a static archive. 3.2 Otherwise, print a warning. Go to 1.2 Note: we don't overwrite <file> because the user might have inadvertently specified a wrong file. 4: Read CDSFileMapHeaderBase._version 4.1 if the version cannot be read, or is less than 12, print a warning. Go to 1.2 4.2 if the version is not CURRENT_CDS_ARCHIVE_VERSION, go to 2. 4.3 Note: the path of the base archive (see section item 5) can be reliably read only for version 12 or later, see JDK-8273152). 5: Read the path of the recorded base archive from <file> 5.1 If the recorded base archive is not the JDK's default archive, print a warning and go to 1.2. 5.2 If the JDK's default archive cannot be loaded, print a warning. Go to 1.2 6: Read the jvm_ident from <file> 6.1 If the reading fails -- Print a warning. Go to 1.2 6.2 if jvm_ident does not match the current JVM, go to 2 7: Attempt to map <file> as the dynamic archive 7.1 if this fails, the reasons are: 7.1.1 Out-of-memory, or I/O problems: these are system-level errors, and we should not re-generate the archive 7.1.2 The file is corrupted: this should not happen normally. The user should know about it. 7.1.3 classpath mismatch: it's likely that the user made a problem in setting up the command-line. We should warn the user. In all the above cases, print a warning message. 7.1.4 - Continue VM execution with only the mapped base archive. - <file> will NOT be regenerated at VM exit Case (B) TBD this is complicated and is probably not a common usage. Maybe we should not support this case in the current RFE) * 20: <base> doesn't exist, or fails to be loaded 20.1 Print a warning 20.1 Goto 1.2 21: <file> doesn't exist 21.1 Go to 2 22: CDSFileMapHeaderBase._magic cannot be read, or is not CDS_DYNAMIC_ARCHIVE_MAGIC: 22.1 Print a warning. Go to 7.1.4 23: Read CDSFileMapHeaderBase._version 23.1 if the version cannot be read, or is less than 12, print a warning. Go to 7.1.4 23.2 if the version is not CURRENT_CDS_ARCHIVE_VERSION, go to 2. 24: Read the path of the recorded base archive from <file> 24.1 If the reading fails -- Print a warning. Go to 7.1.4 24.2 the base archive specified in <file> is not <base>. This is user error -- Print a warning. Go to 7.1.4. 25: Read the jvm_ident from <file> 25.1 If the reading fails -- Print a warning. Go to 7.1.4 25.2 if jvm_ident does not match the current JVM, go to 2 26: Go to 7 ``` Notes - The warning messages should be printed with `log_warning(cds)("...");`
29-09-2021
Moving to Approved.
20-09-2021
[~mseledtsov] please add yourself as a reviewer. [~iklam] I think you can move this to Finalized
17-09-2021
This proposal looks good to me.
17-09-2021
[~dholmes] I've moved the detailed error specification into a comment and explicitly stated that it's not part of the CSR. I needed to put the (rich) text here because JIRA doesn't allow rich text in the main RFE :-(
16-09-2021
This seems fine to me, with no compatibility concerns for the new flag. The "error specification" does not need to be so elaborate or detailed as it exposes a lot of implementation detail. A good guide for what to put in the specification section would be the help information for this flag in the Java manpage.
15-09-2021