Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

8268388: Update large pages information in Java manpage #4425

Closed
wants to merge 3 commits into from
Closed

8268388: Update large pages information in Java manpage #4425

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fceaf55
8268388: Update large pages information in Java manpage
kstefanj Jun 9, 2021
b903205
Thomas review.
kstefanj Jun 9, 2021
0b9b079
Stufe review.
kstefanj Jun 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
117 changes: 64 additions & 53 deletions src/java.base/share/man/java.1
View file
Open in desktop
Expand Up @@ -1403,22 +1403,23 @@ comma.
.RE
.TP
.B \f[CB]\-XX:LargePageSizeInBytes=\f[R]\f[I]size\f[R]
Sets the maximum size (in bytes) for large pages used for the Java heap.
The \f[I]size\f[R] argument must be a power of 2 (2, 4, 8, 16, and so
on).
Sets the maximum large page size (in bytes) used by the JVM.
The \f[I]size\f[R] argument must be a valid page size supported by the
environment to have any effect.
Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes,
\f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or
\f[CB]G\f[R] to indicate gigabytes.
By default, the size is set to 0, meaning that the JVM chooses the size
for large pages automatically.
By default, the size is set to 0, meaning that the JVM will use the
default large page size for the environment as the maximum size for
large pages.
See \f[B]Large Pages\f[R].
.RS
.PP
The following example describes how to set the large page size to 4
megabytes (MB):
The following example describes how to set the large page size to 1
gigabyte (GB):
.RS
.PP
\f[CB]\-XX:LargePageSizeInBytes=4m\f[R]
\f[CB]\-XX:LargePageSizeInBytes=1g\f[R]
.RE
.RE
.TP
Expand Down Expand Up @@ -5122,7 +5123,7 @@ applications may have better performance.
.PP
However, large pages page memory can negatively affect system
performance.
kstefanj marked this conversation as resolved.
Show resolved Hide resolved
For example, when a large mount of memory is pinned by an application,
For example, when a large amount of memory is pinned by an application,
it may create a shortage of regular memory and cause excessive paging in
other applications and slow down the entire system.
Also, a system that has been up for a long time could produce excessive
Expand All @@ -5133,74 +5134,84 @@ When this happens, either the OS or JVM reverts to using regular pages.
Linux and Windows support large pages.
.SS Large Pages Support for Linux
.PP
The 2.6 kernel supports large pages.
Some vendors have backported the code to their 2.4\-based releases.
To check if your system can support large page memory, try the
following:
Linux supports large pages since version 2.6.
To check if your environment supports large pages, try the following:
.IP
.nf
\f[CB]
#\ cat\ /proc/meminfo\ |\ grep\ Huge
HugePages_Total:\ 0
HugePages_Free:\ 0
\&...
Hugepagesize:\ 2048\ kB
\f[R]
.fi
.PP
If the output shows the three "Huge" variables, then your system can
support large page memory but it needs to be configured.
If the command prints nothing, then your system doesn\[aq]t support
large pages.
To configure the system to use large page memory, login as
\f[CB]root\f[R], and then follow these steps:
.IP "1." 3
If you\[aq]re using the option \f[CB]\-XX:+UseSHM\f[R] (instead of
\f[CB]\-XX:+UseHugeTLBFS\f[R]), then increase the \f[CB]SHMMAX\f[R] value.
It must be larger than the Java heap size.
On a system with 4 GB of physical RAM (or less), the following makes all
the memory sharable:
.RS 4
If the output contains items prefixed with "Huge", then your system
supports large pages.
The values may vary depending on environment.
The \f[CB]Hugepagesize\f[R] field shows the default large page size in
your environment, and the other fields show details for large pages of
this size.
Newer kernels have support for multiple large page sizes.
To list the supported page sizes, run this:
.IP
.nf
\f[CB]
#\ ls\ /sys/kernel/mm/hugepages/
hugepages\-1048576kB\ \ hugepages\-2048kB
\f[R]
.fi
.PP
The above environment supports 2 MB and 1 GB large pages, but they need
to be configured so that the JVM can use them.
When using explicit large pages (options \f[CB]\-XX:+UseSHM\f[R] or
\f[CB]\-XX:+UseHugeTLBFS\f[R]), the number of large pages must be
pre\-allocated.
For example, to enable 8 GB of memory to be backed by 2 MB large pages,
login as \f[CB]root\f[R] and run:
.RS
.PP
\f[CB]#\ echo\ 4294967295\ >\ /proc/sys/kernel/shmmax\f[R]
\f[CB]#\ echo\ 4096\ >\ /sys/kernel/mm/hugepages/hugepages\-2048kB/nr_hugepages\f[R]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • vm.nr_hugepages is not the only way to do this setup, since we have vm.nr_overcommit_hugepages, which are a bit more flexible to use. Is the java man page supposed to be complete in explaining this, or should it only show one possible way of many?
  • most users probably just use UseLargePages and are not aware of the different flavors. So they would not know what "explicit" means. How about, instead of mentioning UseSHM and UseHugeTLBFS, not just: "if you use large pages but don't use transparent huge pages (UseTransparentHugePages), large pages need to be preallocated...".
  • Otherwise, at least reverse the order of the two options? UseSHM is mentioned first, which is maybe historical, but TLBFS is the standard.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

* vm.nr_hugepages is not the only way to do this setup, since we have vm.nr_overcommit_hugepages, which are a bit more flexible to use. Is the java man page supposed to be complete in explaining this, or should it only show one possible way of many?

I think mentioning one way to configure it is fine, we don't want to try to cover every possibility. I mean there are multiple ways of specifying each of the options as well. Most advanced users will likely refer to the kernel documentation for more details. I see this as a short explanation of one way to enable large pages.

* most users probably just use UseLargePages and are not aware of the different flavors. So they would not know what "explicit" means. How about, instead of mentioning UseSHM and UseHugeTLBFS, not just: "if you use large pages but don't use transparent huge pages (UseTransparentHugePages), large pages need to be preallocated...".

Something like:

- When using explicit large pages (options `-XX:+UseSHM` or `-XX:+UseHugeTLBFS`), the number of...
+ When using large pages and not enabling transparent huge pages (option `-XX:+UseTransparentHugePages`), the number of...

* Otherwise, at least reverse the order of the two options? UseSHM is mentioned first, which is maybe historical, but TLBFS is the standard.

Good point, I reversed the order of configuring the tow but forgot it here. But going with the above is better I thing.

.RE
.RE
.IP "2." 3
If you\[aq]re using the option \f[CB]\-XX:+UseSHM\f[R] or
\f[CB]\-XX:+UseHugeTLBFS\f[R], then specify the number of large pages.
In the following example, 3 GB of a 4 GB system are reserved for large
pages (assuming a large page size of 2048kB, then 3 GB = 3 * 1024 MB =
3072 MB = 3072 * 1024 kB = 3145728 kB and 3145728 kB / 2048 kB = 1536):
.RS 4
.PP
It is always recommended to check the value of \f[CB]nr_hugepages\f[R]
after the request to make sure the kernel was able to allocate the
requested number of large pages.
.PP
When using the option \f[CB]\-XX:+UseSHM\f[R] to enable large pages you
also need to make sure the \f[CB]SHMMAX\f[R] parameter is configured to
allow large enough shared memory segments to be allocated.
To allow a maximum shared segment of 8 GB, login as \f[CB]root\f[R] and
run:
.RS
.PP
\f[CB]#\ echo\ 1536\ >\ /proc/sys/vm/nr_hugepages\f[R]
\f[CB]#\ echo\ 8589934592\ >\ /proc/sys/kernel/shmmax\f[R]
.RE
.PP
In some environments this is not needed since the default value is large
enough, but it is important to make sure the value is large enough to
fit the amount of memory intended to be backed by large pages.
.RS
.PP
\f[B]Note:\f[R] The values contained in \f[CB]/proc\f[R] resets after you
reboot your system, so may want to set them in an initialization script
(for example, \f[CB]rc.local\f[R] or \f[CB]sysctl.conf\f[R]).
\f[B]Note:\f[R] The values contained in \f[CB]/proc\f[R] and \f[CB]/sys\f[R]
reset after you reboot your system, so may want to set them in an
initialization script (for example, \f[CB]rc.local\f[R] or
\f[CB]sysctl.conf\f[R]).
.RE
.RE
.IP \[bu] 2
If you configure (or resize) the OS kernel parameters
\f[CB]/proc/sys/kernel/shmmax\f[R] or \f[CB]/proc/sys/vm/nr_hugepages\f[R],
Java processes may allocate large pages for areas in addition to the
Java heap.
These steps can allocate large pages for the following areas:
.RS 2
.IP \[bu] 2
Java heap
.PP
If you configure the OS kernel parameters to enable use of large pages,
the Java processes may allocate large pages for the Java heap as well as
other internal areas, for example:
.IP \[bu] 2
Code cache
.IP \[bu] 2
The marking bitmap data structure for the parallel GC
Marking bitmaps
.PP
Consequently, if you configure the \f[CB]nr_hugepages\f[R] parameter to
the size of the Java heap, then the JVM can fail in allocating the code
cache areas on large pages because these areas are quite large in size.
.RE
the size of the Java heap, then the JVM can still fail to allocate the
heap using large pages because other areas such as the code cache might
already have used some of the configured large pages.
.SS Large Pages Support for Windows
.PP
To use large pages support on Windows, the administrator must first
Expand Down