Summary
-------

Change the meaning of `LargePageSizeInBytes` to be the maximum large page size the JVM may use (not the only one). A default value of zero will mean to allow the JVM use large page sizes up to the environment's default large page size.

Problem
-------

Currently the JVM only uses a single large page size for large memory allocations. This may either be the environment's default large page size if `LargePageSizeInBytes` is zero, or the value specified in `LargePageSizeInBytes`.

If multiple large page sizes are configured there is no possibility to leverage all of the available large page sizes. This can lead to sub-optimal use of memory as large pages may need to be pre-allocated in the environment and reduced performance because not all page sizes are suitable for all memory allocations in the JVM.

The Java man page already defines `LargePageSizeInBytes` as the maximum size the JVM may use: 

----------


`-XX:LargePageSizeInBytes=`*size*
:   Sets the maximum size (in bytes) for large pages used for the Java heap.
    The *size* argument must be a power of 2 (2, 4, 8, 16, and so on). Append
    the letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate
    megabytes, or `g` or `G` to indicate gigabytes. By default, the size is
    set to 0, meaning that the JVM chooses the size for large pages
    automatically. See [Large Pages].

    The following example describes how to set the large page size to 4
    megabytes (MB):

    >   `-XX:LargePageSizeInBytes=4m`


----------

The implementation did not exploit this specification until now.

Solution
--------

The value of `LargePageSizeInBytes` will always define the maximum large page size the JVM may use out of the ones configured in the environment. If the user does not specify `LargePageSizeInBytes` on the command line or sets it to zero, the JVM will use the default large page size for the environment for the maximum large page size.

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

Changes made to the HotSpot code to update the flag:

    diff --git a/src/hotspot/share/runtime/globals.hpp b/src/hotspot/share/runtime/globals.hpp
    index cfe5fd8116c..2d09075fb48 100644
    --- a/src/hotspot/share/runtime/globals.hpp
    +++ b/src/hotspot/share/runtime/globals.hpp
    @@ -239,7 +239,8 @@ const intx ObjectAlignmentInBytes = 8;
               "Use intrinsics for java.util.Base64")                            \
                                                                                 \
       product(size_t, LargePageSizeInBytes, 0,                                  \
    -          "Large page size (0 to let VM choose the page size)")             \
    +          "Maximum large page size used (0 will use the default large "     \
    +          "page size for the environment as the maximum)")                  \
               range(0, max_uintx)                                               \
                                                                                 \
       product(size_t, LargePageHeapSizeThreshold, 128*M,                        \


Changes are also required for the Java man pages, here is a proposal:


----------
`-XX:LargePageSizeInBytes=`*size*
:   Sets the maximum large page size (in bytes) to use by the JVM. The
    *size* argument must be a valid large page size supported by the
    environment to have any effect. Append the letter `k` or `K` to indicate
    kilobytes, `m` or `M` to indicate megabytes, or `g` or `G` to
    indicate gigabytes.
    By default, the value of this option is set to 0, meaning that the JVM
    will use the default large page size for the environment as the maximum large page size.
    See [Large Pages].

    The following example describes how to set the large page size to 1
    gigabyte (GB):

    >   `-XX:LargePageSizeInBytes=1g`


----------