New CML option to adjust storage of extra startup hints

#1433

New parameter 'extraStartupHints` added to the -Xshareclasses topic. Incorporated feedback.

Closes #1433
Signed-off-by: Sreekala Gopakumar [email protected]

docs/version0.49.md

@@ -27,6 +27,7 @@ The following new features and notable changes since version 0.48.0 are included
 
 - [New binaries and changes to supported environments](#binaries-and-supported-environments)
 - [Change to the shared classes cache generation number](#change-to-the-shared-classes-cache-generation-number)
+- [New shared classes cache suboption added to adjust the number of startup hints that can be stored](#new-shared-classes-cache-suboption-added-to-adjust-the-number-of-startup-hints-that-can-be-stored)
 
 ## Features and changes
 
@@ -46,6 +47,12 @@ To save space, all existing shared caches can be removed unless they are in use
 
 The shared classes cache generation number is modified because of a change in the format of ROMClasses that are stored in the shared classes cache. A new flag `J9AccClassIsShared` is added to ROMClasses to indicate whether a ROMClass was loaded from a shared classes cache or from a VM.
 
+### New shared classes cache suboption added to adjust the number of startup hints that can be stored
+
+You can use the `-Xshareclasses:extraStartupHints=<number>` option to adjust the number of startup hints that can be stored in a shared cache. By default, you can store only up to 64 startup hints in a shared cache.
+
+For more information, see [`-Xshareclasses:extraStartupHints`](xshareclasses.md#extrastartuphints).
+
 ## Known problems and full release information
 
 To see known problems and a complete list of changes between Eclipse OpenJ9 v0.48.0 and v0.49.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.49/0.49.md).

docs/xshareclasses.md

@@ -239,6 +239,16 @@ case, the VM continues without using shared classes.
 
 : Destroys all caches that are unused for the time that is specified before loading shared classes. This option is not a utility option because it does not cause the VM to exit. On Windows systems, which have NTFS file systems, the `expire` option is accurate to the nearest hour.
 
+### `extraStartupHints`
+
+        -Xshareclasses:extraStartupHints=<number>
+
+: where, `<number>` is greater than or equal to 0.
+
+: Adjusts the number of startup hints that can be stored in a shared cache. By default, you can store only up to 64 startup hints in a shared cache. This count decrements by 1 each time a startup hint is stored. After the count reaches 0, no more hints can be added to the cache. You can use `-Xshareclasses:extraStartupHints=<number>` to adjust this count as needed. For example, `-Xshareclasses:extraStartupHints=0` prevents any new hints to be stored and `-Xshareclasses:extraStartupHints=10` allows 10 more new hints in addition to the default number of 64 startup hints.
+
+: You can use [`-Xshareclasses:printStats=startuphint`](#printstats-cache-utility) to check how many startup hints are already stored in the shared cache. You can also use [`-Xshareclasses:printDetails`](#printdetails-cache-utility) to check how many hints in addition to the default startup hints can be stored in the cache. In the output of the `printDetails` suboption, the number of extra startup hints that can be stored is found on the line `# Additional startup hints allowed`.
+
 ### `fatal`
 
         -Xshareclasses:fatal
@@ -466,6 +476,12 @@ behavior, which can improve the performance of class loading from the shared cla
 
 :   Displays detailed information about the contents of the cache that is specified in the [`name`](#name) suboption. If the name is not specified, statistics are displayed about the default cache. For layered caches, information is shown for all layers (to see information for the top layer cache only, use [`printTopLayerStats=all`](#printtoplayerstats-cache-utility)). Every class is listed in chronological order with a reference to the location from which it was loaded. For more information, see [Shared classes cache diagnostic utilities](shrc_diag_util.md#shared-classes-cache-diagnostic-utilities).
 
+### `printDetails` (Cache utility)
+
+        -Xshareclasses:printDetails
+
+:   Displays detailed cache statistics. The output of this suboption is similar to the output of [`-Xshareclasses:printStats`](#printstats-cache-utility) but with additional information. For example, instead of "AOT bytes" which is a total, the output shows "AOT code bytes", "AOT data bytes", "AOT class hierarchy bytes", and "AOT thunk bytes".
+
 ### `printStats` (Cache utility)
 
         -Xshareclasses:printStats=<data_type>[+<data_type>]