On Fri, Dec 1, 2017 at 10:09 PM, Thomas Munro
<thomas.mu...@enterprisedb.com> wrote:
>> On 11/30/17 23:35, Thomas Munro wrote:
>>> Hmm. Yeah, it does, but apparently it's not so transparent. So if we
>>> mention that we'd better indicate in the same paragraph that you
>>> probably don't actually want to use it. How about the attached?
Here's a review for v3.
I find that the first paragraph is an improvement as it's more precise.
What I didn't like about the second paragraph is that it pointed out
Linux transparent huge pages too favorably while they are actually
known to cause big (huge?, pardon the pun) issues (as witnessed in
this thread as well). v3 basically says "in Linux it can be
transparent or explicit and explicit is faster than transparent".
Reading that, and seeing that explicit needs tweaking of kernel
parameters and so on, one might very well conclude "I'll use the
slightly-slower-but-still-better-than-nothing transparent version".
So I tried to redo the second paragraph and ended up with the
attached. Rationale for the changes:
* changed "this feature" to "explicitly requesting huge pages" to
contrast with the automatic one described below
* made the wording of Linux THP more negative (but still with some
wiggle room for future kernel versions which might improve THP),
contrasting with the positive explicit request from this GUC
* integrated your mention of other OSes with automatic huge pages
* moved the new text to the last paragraph to lower its importance
What do you think?
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index e4a01699e4..b6b309a943 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1363,14 +1363,15 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
- Enables/disables the use of huge memory pages. Valid values are
- <literal>try</literal> (the default), <literal>on</literal>,
- and <literal>off</literal>.
+ Controls whether huge memory pages are requested for the main shared
+ memory area. Valid values are <literal>try</literal> (the default),
+ <literal>on</literal>, and <literal>off</literal>.
</para>
<para>
- At present, this feature is supported only on Linux. The setting is
- ignored on other systems when set to <literal>try</literal>.
+ At present, explicitly requesting huge pages is supported only on
+ Linux. The setting is ignored on other systems when set to
+ <literal>try</literal>.
</para>
<para>
@@ -1386,6 +1387,18 @@ include_dir 'conf.d'
to use huge pages will prevent the server from starting up. With
<literal>off</literal>, huge pages will not be used.
</para>
+
+ <para>
+ Note that, besides explicitly requesting huge pages via
+ <varname>huge_pages</varname>, operating systems including Linux,
+ FreeBSD and Illumos can also use huge pages (sometimes known as "super"
+ pages or "large" pages) automatically, without an explicit request from
+ <productname>PostgreSQL</productname>. In Linux this automatic use is
+ called "transparent huge pages" but, for some Linux kernel versions,
+ transparent huge pages are known to cause performance degradation with
+ <productname>PostgreSQL</productname> so, unlike
+ <varname>huge_pages</varname>, their use is discouraged.
+ </para>
</listitem>
</varlistentry>
