Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot
David Holmes
david.holmes at oracle.com
Wed Feb 21 07:27:27 UTC 2018
Dear CSR Group Members,
On behalf of the Hotspot team within Oracle, I would like to submit this
proposal regarding the CSR process for dealing with various -XX Hotspot
flags.
If this is acceptable then we would like to see this clearly documented
on the OpenJDK site in a suitable location (and referenced from both
Hotspot wiki and CSR wiki).
Thank you.
David
------
Summary:
=======
The Hotspot team would like to exempt the addition and removal of
developer-oriented command-line flags from the need for a CSR request,
and to streamline the removal process for other flags.
Background:
==========
Hotspot defines 6 kinds of command-line flags:
- product
These are the primary flags we intend end-users to apply for tuning,
feature selection etc. These are settable via the command-line in
product builds.
- manageable
These are a special kind of product flag that can be dynamically set via
the JDK management interface.
- develop
These are flags intended for use by Hotspot developers for debugging and
testing purposes. These are settable only in non-product builds, and
have a constant value in product builds.
- not_product
A more constrained development flag that has no presence at all in a
product build.
- experimental
These flags are in support of features that are not part of the
officially supported product, but are available in the product for
experimenting with. They must be explicitly unlocked to be used. They
are expected to be temporary in nature, and potentially replaced by a
product flag in a later release if the feature remains. Experimental
features can be dropped with no notice.
- diagnostic
Diagnostic flags are not meant for VM tuning or for product modes. They
are to be used for VM quality assurance or field diagnosis of VM bugs.
They are hidden so that users will not be encouraged to try them as if
they were product flags. However, they are available in the product
version of the VM so they can be enabled under instruction
to collect diagnostic information about VM problems.
The Hotspot team have a defined (up to) three step deprecation process
for removing flags:
1. Deprecate: accept the flag, act on it, but warn it is deprecated and
may be removed in the future.
2. Obsolete: accept the flag but ignore it other than to issue a warning
it is obsolete and may be removed in the future. This allows code
associated with the flag to be removed from the codebase.
3. Expired: use of the flag causes an "unknown VM option" error and the
VM refuses to start.
The full three step process is used for "product" and "manageable"
flags. For the other flags we can start at step 2 and "obsolete" the
flag in the current release.
The CSR Process:
===============
From the Developers Guide [1] we have the definition of "Official" and
"Unofficial" interfaces, in which it describes as official interfaces "
... and the names of the options taken by those commands". Which
indicates the Hotspot -XX options are all to be considered part of an
"Official interface" (which is different to how they were considered
under the old CCC).
The CSR FAQ also has:
Q: What sort of changes require CSR review?
A: Any change to a JDK interface meant to be used outside of the JDK
itself requires CSR review. In this context "interface" isn't limited to
the Java programing language definition of an interface, but encompasses
the broader concept of a protocol between the JDK and users of the JDK.
Examples of interfaces by this definition include:
...
Adding, removing, or changing a command line option
so again this places all -XX options into the same CSR basket.
Proposed Changes:
=================
We propose that only "product" and "manageable" flags should be
considered part of the "official interface" and subject to the full CSR
process.
For the other flags, given their nature as part of the "unofficial
interface", we feel the CSR process is not needed and the code review
process gives sufficient visibility to the change.
Separately, though related, we will also look into how to document these
flags in a manner suitable for developers.
We further wish to clarify that for the "product" and "manageable"
flags, the CSR request made when the flag is initially deprecated,
serves to cover the entire removal process. That is, we do not need to
submit further CSR requests when the flag is obsoleted, and then expired.
[1]
http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html#kinds_of_interfaces
More information about the csr-discuss
mailing list