Semantics of `-Xmn`

[Ramakrishna, Ramki]

Question: Can `-Xmn` be interpreted as "fix young gen size to the specified value, not allowing any resizing"?

$ java -X
...
    -Xmn<size>        sets the initial and maximum size (in bytes) of the heap
                      for the young generation (nursery)
    -Xms<size>        set initial Java heap size
    -Xmx<size>        set maximum Java heap size
...

Note that this states "sets the initial and maximum size", as though one might be allowed to make the size smaller, but never larger than this.

Similarly `-Xms` sets the initial heap size and `-Xmx` the maximum heap size. Would one be allowed to make the heap size smaller than the `-Xms` specification

It seems as though at least historically one has (implicitly) identified "initial" with "minimum". Thus, we have asked customers to set `-Xms` and `-Xmx` to the same value to prevent changes to the heap size. Similarly also for `-XX:NewSize`  (there isn't a `-XX:MinNewSize` option, like `-XX:MaxNewSize`).

Indeed the following comment in `g1YoungSizer.hpp` articulates this "initial is minimum" interpretation:

// There are three command line options related to the young gen size:
// NewSize, MaxNewSize and NewRatio (There is also -Xmn, but that is
// just a short form for NewSize==MaxNewSize). G1 will use its internal
// heuristics to calculate the actual young gen size, so these options
// basically only limit the range within which G1 can pick a young gen
// size. Also, these are general options taking byte sizes. G1 will
// internally work with a number of regions instead. So, some rounding
// will occur.
//
// If nothing related to the young gen size is set on the command
// line we should allow the young gen to be between G1NewSizePercent
// and G1MaxNewSizePercent of the heap size. This means that every time
// the heap size changes, the limits for the young gen size will be
// recalculated.
//
// If only -XX:NewSize is set we should use the specified value as the
// minimum size for young gen. Still using G1MaxNewSizePercent of the
// heap as maximum.
//
// If only -XX:MaxNewSize is set we should use the specified value as the
// maximum size for young gen. Still using G1NewSizePercent of the heap
// as minimum.
//
// If -XX:NewSize and -XX:MaxNewSize are both specified we use these values.
// No updates when the heap size changes. There is a special case when
// NewSize==MaxNewSize. This is interpreted as "fixed" and will use a
// different heuristic for calculating the collection set when we do mixed
// collection.
//
// If only -XX:NewRatio is set we should use the specified ratio of the heap
// as both min and max. This will be interpreted as "fixed" just like the
// NewSize==MaxNewSize case above. But we will update the min and max
// every time the heap size changes.
//
// NewSize and MaxNewSize override NewRatio. So, NewRatio is ignored if it is
// combined with either NewSize or MaxNewSize. (A warning message is printed.)

So if the answer to the question I asked at the start is "Yes", perhaps we should also fix the verbage of the `java -X` text to explicitly state "initial and minimum" instead of just "initial" for those cases?

Thanks for any thoughts/comments/corrections.
-- Ramki