Semantics of `-Xmn`

[Stefan Karlsson]

On 2022-12-04 03:38, Ramakrishna, Ramki wrote:
> 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.

FWIW, a few years ago we went over some of the documentation around 
`-Xms` to make it clear that that it meant both "initial" and "minimum". 
It would probably be good to change the `java -X` output as well.

I'll let others comment about the `-Xmn` flag.

StefanK

>   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
>
>