Summary
-------

Validate the arguments to all JVM command-line flags so as to avoid
crashes, and ensure that appropriate error messages are displayed when
they are invalid.


Non-goals
---------

 - We will not validate arguments to flags that are not processed by
   the JVM.

 - We will not attempt to adjust arguments to fall within allowed
   ranges; we will only detect incorrect arguments, not correct them.


Success Metrics
---------------

Any JVM flag that takes a value and is provided an out-of-range value is
shown to not cause a JVM crash but rather issue an informative error
message.  This will be done for JVM flags whether they are set
ergonomically (e.g., in include files), set on the command line, set via
tool input, or set via APIs (e.g., `attachListener`/`jcmd`, or
`java.lang.management`).


Description
-----------

Any interface, whether it be programmatic or user-visible, must provide
adequate capability to validate input values.  In the case of command
lines, it is critical to implement range checks for arguments which
require a user-specified value.  The `globals.hpp` source file contains
the origin of the flag value and rudimentary range checking.  Expanding
and completing this can provide correct coverage.

In addition, we should define a framework to make it very easy for
someone adding a new JVM command-line flag to take advantage of this
validity checking.  The framework should be flexible, allowing for checks
of a single value, being between a minimum and maximum value, or being
within a set of values, etc.

We will implement this feature by expanding existing macro tables (e.g.,
`RUNTIME_FLAGS`) to add optional `range(min, max)` and
`constraint(function_pointer)` entries.  Current range-checking and other
ad-hoc validation code will be ported over and then removed.

The range and constraints checks are done every time a flag changes, as
well as late in the JVM initialization routine (i.e., in `init_globals()`
after `stubRoutines_init2()`) at the time when all flags have their final
values set.  We will continue to check the manageable flags as long as
the JVM runs.

For those flags that depend on others that might not be set at the time
of setting the flag in question, we will provide a mechanism in form of
an API (`CommandLineFlags::finishedInitializing()`) to let constraint
functions know when all flags have their final values set and change
their behavior from NOP to error as needed.

Intercepting flag value changes is done at a low level in
`CommandLineFlags::xxxxAtPut` setters to guarantee that manageable flags
are checked for their ranges and constraints (e.g., flags set via
`jcmd`).  For example, using `jcmd PID VM.set_flag MinHeapFreeRatio 101`,
which is outside the allowed range, will print out

    PID:
    MinHeapFreeRatio error: must have value in range [0...100]

in the `jcmd` output.

The range checks do not impose any behavioral changes upon the JVM
initialization process.  In particular they do not terminate the JVM, but
instead they propagate their status up to the code that uses them.  The
constraint functions can terminate the JVM to match existing custom
behavior as needed.

The range/constraint checks are non-verbose by default, to inhibit their
messages from being printed out.  Range checks do print error messages on
the error stream during JVM initialization, in order to match current
behavior.  Printing to the error stream for manageable flags is
inhibited; any error status will, rather, be handled by the
`WriteableFlags` code to provide verbose status into the provided
`FormatBuffer` so that it can be then printed by `jcmd` process itself
instead of by the target process.

In the event of range-check failure during JVM initialization, an error
message is printed by default in the following form:

    uintx UnguardOnExecutionViolation = 3 is outside the allowed range [ 0 ... 2 ]

We are not, however, committing to any particular format at this
time.  Existing tests that expect a certain message format will have to
be modified to allow the new format.

The existing behavior is not changed with respect to clamping flags to
fit within a specified range (i.e., we do not clamp), even though we have
that capability.  We conform to the existing behavior during error
detection while initializing the JVM (i.e., we terminate the process).


Alternatives
------------

Variadic macros offered a slightly different, and possibly a cleaner, way
to define ranges and constraints, but a "trailing comma with empty args"
issue in the Solaris C++ compiler prevented the adoption of this
approach.