From 2a5ecb56d22340a00393fa60e7b910c472071875 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Thu, 25 Jan 2018 11:14:24 -0500
Subject: [PATCH] Update documentation to mention huge pages on other OSes

Previously, the docs implied that only Linux and Windows could use huge
pages.  That's not quite true: it's just that we only know how to
request them explicitly on those OSes.  Be more explicit about what
huge_pages really does and mention that some OSes may use huge pages
automatically.

Author: Thomas Munro and Catalin Iacob
Reviewed-By: Justin Pryzby, Peter Eisentraut
Discussion: https://postgr.es/m/CAEepm=3qzR-hfjepymohuC4XO5phxoSoipOjm6BEhnJHjNR+jg@mail.gmail.com
---
 doc/src/sgml/config.sgml | 33 +++++++++++++++++++++++----------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 45b2af14eb..f951ddb41e 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1372,14 +1372,20 @@ 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 pages are requested for the main shared memory
+        area. Valid values are <literal>try</literal> (the default),
+        <literal>on</literal>, and <literal>off</literal>.  With
+        <varname>huge_pages</varname> set to <literal>try</literal>, the
+        server will try to request huge pages, but fall back to the default if
+        that fails. With <literal>on</literal>, failure to request huge pages
+        will prevent the server from starting up. With <literal>off</literal>,
+        huge pages will not be requested.
        </para>
 
        <para>
-        At present, this feature is supported only on Linux and Windows. The
-        setting is ignored on other systems when set to <literal>try</literal>.
+        At present, this setting is supported only on Linux and Windows. The
+        setting is ignored on other systems when set to
+        <literal>try</literal>.
        </para>
 
        <para>
@@ -1401,11 +1407,18 @@ include_dir 'conf.d'
        </para>
 
        <para>
-        With <varname>huge_pages</varname> set to <literal>try</literal>,
-        the server will try to use huge pages, but fall back to using
-        normal allocation if that fails. With <literal>on</literal>, failure
-        to use huge pages will prevent the server from starting up. With
-        <literal>off</literal>, huge pages will not be used.
+        Note that this setting only affects the main shared memory area.
+        Operating systems such as Linux, FreeBSD, and Illumos can also use
+        huge pages (also known as <quote>super</quote> pages or
+        <quote>large</quote> pages) automatically for normal memory
+        allocation, without an explicit request from
+        <productname>PostgreSQL</productname>. On Linux, this is called
+        <quote>transparent huge pages</quote><indexterm><primary>transparent
+        huge pages</primary></indexterm> (THP). That feature has been known to
+        cause performance degradation with
+        <productname>PostgreSQL</productname> for some users on some Linux
+        versions, so its use is currently discouraged (unlike explicit use of
+        <varname>huge_pages</varname>).
        </para>
       </listitem>
      </varlistentry>