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