Improve documentation about use of Linux huge pages.

Show how to get the system's huge page size, rather than misleadingly
referring to PAGE_SIZE (which is usually understood to be the regular
page size).  Show how to confirm whether huge pages have been allocated.
Minor wordsmithing.  Back-patch to 9.4 where this section appeared.

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 4f73c043ac5e2c735dec0c2a8b93302a2b958d50..dec98187cb6c47c764d95c3857147ee2263f3279 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1422,53 +1422,67 @@ export PG_OOM_ADJUST_VALUE=0
   
 
   
-   Linux <span class="marked">huge p</span>ages
+   Linux <span class="marked">Huge P</span>ages
 
    
     Using huge pages reduces overhead when using large contiguous chunks of
-    memory, like PostgreSQL does. To enable this
+    memory, as PostgreSQL does, particularly when
+    using large values of .  To use this
     feature in PostgreSQL you need a kernel
     with CONFIG_HUGETLBFS=y and
-    CONFIG_HUGETLB_PAGE=y. You also have to tune the system
-    setting vm.nr_hugepages. To estimate the number of
-    necessary huge pages start PostgreSQL without
-    huge pages enabled and check the VmPeak value from the
-    proc file system:
+    CONFIG_HUGETLB_PAGE=y. You will also have to adjust
+    the kernel setting vm.nr_hugepages. To estimate the
+    number of huge pages needed, start PostgreSQL
+    without huge pages enabled and check the
+    postmaster's VmPeak value, as well as the system's
+    huge page size, using the /proc file system.  This might
+    look like:
 
-$ head -1 /path/to/data/directory/postmaster.pid
+$ head -1 $PGDATA/postmaster.pid
 4170
 $ grep ^VmPeak /proc/4170/status
 VmPeak:  6490428 kB
+$ grep ^Hugepagesize /proc/meminfo
+Hugepagesize:       2048 kB
 
-     6490428 / 2048
-     (PAGE_SIZE is 2MB in this case) are
-     roughly 3169.154 huge pages, so you will need at
-     least 3170 huge pages:
+     6490428 / 2048 gives approximately
+     3169.154, so in this example we need at
+     least 3170 huge pages, which we can set with:
 
 $ sysctl -w vm.nr_hugepages=3170
 
+    A larger setting would be appropriate if other programs on the machine
+    also need huge pages.  Don't forget to add this setting
+    to /etc/sysctl.conf so that it will be reapplied
+    after reboots.
+   
+
+   
     Sometimes the kernel is not able to allocate the desired number of huge
-    pages, so it might be necessary to repeat that command or to reboot. Don't
-    forget to add an entry to /etc/sysctl.conf to persist
-    this setting through reboots.
+    pages immediately, so it might be necessary to repeat the command or to
+    reboot.  (Immediately after a reboot, most of the machine's memory
+    should be available to convert into huge pages.)  To verify the huge
+    page allocation situation, use:
+
+$ grep Huge /proc/meminfo
+
    
 
    
-    It is also necessary to give the database server operating system
+    It may also be necessary to give the database server's operating system
     user permission to use huge pages by setting
-    vm.hugetlb_shm_group via sysctl, and
-    permission to lock memory with ulimit -l.
+    vm.hugetlb_shm_group via sysctl, and/or
+    give permission to lock memory with ulimit -l.
    
 
    
     The default behavior for huge pages in
     PostgreSQL is to use them when possible and
-    to fallback to normal pages when failing. To enforce the use of huge
-    pages, you can set
-    huge_pages
-    to on. Note that in this case
-    PostgreSQL will fail to start if not enough huge
-    pages are available.
+    to fall back to normal pages when failing. To enforce the use of huge
+    pages, you can set 
+    to on in postgresql.conf.
+    Note that with this setting PostgreSQL will fail to
+    start if not enough huge pages are available.