Rename huge_tlb_pages to huge_pages, and improve docs.

Christian Kruse

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index cf11306f6cba5e8e3fdd7cae89ed00a3afa5fa87..065c1dbdcf0d6177d4581ef7b0c1e4f0f7a0989a 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1166,35 +1166,31 @@ include 'filename'
       
      
 
-     tlb-pages" xreflabel="huge_tlb_pages">
-      huge_tlb_pages (enum)
+     pages" xreflabel="huge_pages">
+      huge_pages (enum)
       
-       huge_tlb_pages configuration parameter
+       huge_pages configuration parameter
       
       
        
-        Enables/disables the use of huge TLB pages. Valid values are
+        Enables/disables the use of huge memory pages. Valid values are
         try (the default), on,
         and off.
        
 
        
-        At present, this feature is supported only on Linux. The setting
-        is ignored on other systems.
+        At present, this feature is supported only on Linux. The setting is
+        ignored on other systems when set to try.
        
 
        
-        The use of huge TLB pages results in smaller page tables and
-        less CPU time spent on memory management, increasing performance. For
-        more details, see
-        the Debian wiki.
-        Remember that you will need at least shared_buffers / huge page size +
-        1 huge TLB pages. So for example for a system with 6GB shared buffers
-        and a hugepage size of 2kb of you will need at least 3156 huge pages.
+        The use of huge pages results in smaller page tables and less CPU time
+        spent on memory management, increasing performance. For more details,
+        see .
        
 
        
-        With huge_tlb_pages set to try,
+        With huge_pages set to try,
         the server will try to use huge pages, but fall back to using
         normal allocation if that fails. With on, failure
         to use huge pages will prevent the server from starting up. With

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index bbb808fecb06ed4eec927651280dc96a90d4e9e8..7f4a2358c45382507a561a7b251139911869c784 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1307,6 +1307,57 @@ echo -1000 > /proc/self/oom_score_adj
    
    
   
+
+  
+   Linux huge pages
+
+   
+    Using huge pages reduces overhead when using large contiguous chunks of
+    memory, like PostgreSQL does. To enable 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 filesystem:
+
+$ head -1 /path/to/data/directory/postmaster.pid
+4170
+$ grep ^VmPeak /proc/4170/status
+VmPeak:  6490428 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:
+
+$ sysctl -w vm.nr_hugepages=3170
+
+    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.
+   
+
+   
+    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.
+   
+
+   
+    For a detailed description of the Linux huge
+    pages feature have a look
+    at https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt.
+   
+
+  
  
 
 

diff --git a/src/backend/port/sysv_shmem.c b/src/backend/port/sysv_shmem.c
index 65ad59570cb76ee46a33eeecd31d21e9e5841986..51c1a2b71f85f07b7901907aa8cf364b84d3c0e8 100644 (file)
--- a/src/backend/port/sysv_shmem.c
+++ b/src/backend/port/sysv_shmem.c
@@ -333,12 +333,12 @@ CreateAnonymousSegment(Size *size)
    int         mmap_errno = 0;
 
 #ifndef MAP_HUGETLB
-   if (huge_tlb_pages == HUGE_TLB_ON)
+   if (huge_pages == HUGE_PAGES_ON)
        ereport(ERROR,
                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                 errmsg("huge TLB pages not supported on this platform")));
 #else
-   if (huge_tlb_pages == HUGE_TLB_ON || huge_tlb_pages == HUGE_TLB_TRY)
+   if (huge_pages == HUGE_PAGES_ON || huge_pages == HUGE_PAGES_TRY)
    {
        /*
         * Round up the request size to a suitable large value.
@@ -364,13 +364,13 @@ CreateAnonymousSegment(Size *size)
        ptr = mmap(NULL, allocsize, PROT_READ | PROT_WRITE,
                   PG_MMAP_FLAGS | MAP_HUGETLB, -1, 0);
        mmap_errno = errno;
-       if (huge_tlb_pages == HUGE_TLB_TRY && ptr == MAP_FAILED)
+       if (huge_pages == HUGE_PAGES_TRY && ptr == MAP_FAILED)
            elog(DEBUG1, "mmap with MAP_HUGETLB failed, huge pages disabled: %m");
    }
 #endif
 
-   if (huge_tlb_pages == HUGE_TLB_OFF ||
-       (huge_tlb_pages == HUGE_TLB_TRY && ptr == MAP_FAILED))
+   if (huge_pages == HUGE_PAGES_OFF ||
+       (huge_pages == HUGE_PAGES_TRY && ptr == MAP_FAILED))
    {
        /*
         * use the original size, not the rounded up value, when falling
@@ -431,10 +431,10 @@ PGSharedMemoryCreate(Size size, bool makePrivate, int port)
    Size        sysvsize;
 
 #if defined(EXEC_BACKEND) || !defined(MAP_HUGETLB)
-   if (huge_tlb_pages == HUGE_TLB_ON)
+   if (huge_pages == HUGE_PAGES_ON)
        ereport(ERROR,
                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
-                errmsg("huge TLB pages not supported on this platform")));
+                errmsg("huge pages not supported on this platform")));
 #endif
 
    /* Room for a header? */

diff --git a/src/backend/port/win32_shmem.c b/src/backend/port/win32_shmem.c
index 9b0cceb5309a1ac299c7329fafe4eb3dc42b1117..dca371cce62bf02dfe07a218e1d56c403a26a3c9 100644 (file)
--- a/src/backend/port/win32_shmem.c
+++ b/src/backend/port/win32_shmem.c
@@ -128,10 +128,10 @@ PGSharedMemoryCreate(Size size, bool makePrivate, int port)
    DWORD       size_high;
    DWORD       size_low;
 
-   if (huge_tlb_pages == HUGE_TLB_ON)
+   if (huge_pages == HUGE_PAGES_ON)
        ereport(ERROR,
                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
-                errmsg("huge TLB pages not supported on this platform")));
+                errmsg("huge pages not supported on this platform")));
 
    /* Room for a header? */
    Assert(size > MAXALIGN(sizeof(PGShmemHeader)));

diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c
index b27cb89a289a559e0a553eff40d45d98f8e7c15e..c76edb48a9bb0ce4636ca0c701cb746f305f5643 100644 (file)
--- a/src/backend/utils/misc/guc.c
+++ b/src/backend/utils/misc/guc.c
@@ -393,16 +393,16 @@ static const struct config_enum_entry synchronous_commit_options[] = {
  * Although only "on", "off", "try" are documented, we accept all the likely
  * variants of "on" and "off".
  */
-static const struct config_enum_entry huge_tlb_options[] = {
-   {"off", HUGE_TLB_OFF, false},
-   {"on", HUGE_TLB_ON, false},
-   {"try", HUGE_TLB_TRY, false},
-   {"true", HUGE_TLB_ON, true},
-   {"false", HUGE_TLB_OFF, true},
-   {"yes", HUGE_TLB_ON, true},
-   {"no", HUGE_TLB_OFF, true},
-   {"1", HUGE_TLB_ON, true},
-   {"0", HUGE_TLB_OFF, true},
+static const struct config_enum_entry huge_pages_options[] = {
+   {"off", HUGE_PAGES_OFF, false},
+   {"on", HUGE_PAGES_ON, false},
+   {"try", HUGE_PAGES_TRY, false},
+   {"true", HUGE_PAGES_ON, true},
+   {"false", HUGE_PAGES_OFF, true},
+   {"yes", HUGE_PAGES_ON, true},
+   {"no", HUGE_PAGES_OFF, true},
+   {"1", HUGE_PAGES_ON, true},
+   {"0", HUGE_PAGES_OFF, true},
    {NULL, 0, false}
 };
 
@@ -470,7 +470,7 @@ int         tcp_keepalives_count;
  * This really belongs in pg_shmem.c, but is defined here so that it doesn't
  * need to be duplicated in all the different implementations of pg_shmem.c.
  */
-int            huge_tlb_pages;
+int            huge_pages;
 
 /*
  * These variables are all dummies that don't do anything, except in some
@@ -3497,12 +3497,12 @@ static struct config_enum ConfigureNamesEnum[] =
    },
 
    {
-       {"huge_tlb_pages", PGC_POSTMASTER, RESOURCES_MEM,
-           gettext_noop("Use of huge TLB pages on Linux"),
+       {"huge_pages", PGC_POSTMASTER, RESOURCES_MEM,
+           gettext_noop("Use of huge pages on Linux"),
            NULL
        },
-       &huge_tlb_pages,
-       HUGE_TLB_TRY, huge_tlb_options,
+       &huge_pages,
+       HUGE_PAGES_TRY, huge_pages_options,
        NULL, NULL, NULL
    },
 

diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
index ce56059ceb294b78acae4d5e0c5ede36486002bf..3629a52c9fe43682852a8e88536f4406c765379d 100644 (file)
--- a/src/backend/utils/misc/postgresql.conf.sample
+++ b/src/backend/utils/misc/postgresql.conf.sample
@@ -115,7 +115,7 @@
 
 #shared_buffers = 32MB         # min 128kB
                    # (change requires restart)
-#huge_tlb_pages = try          # on, off, or try
+#huge_pages = try          # on, off, or try
                    # (change requires restart)
 #temp_buffers = 8MB            # min 800kB
 #max_prepared_transactions = 0     # zero disables the feature

diff --git a/src/include/storage/pg_shmem.h b/src/include/storage/pg_shmem.h
index 0d607298fbd5e41f5e19dd879943d2a0985f377b..0dc960b597f99535a1fc3a9149f85d4d17bf0289 100644 (file)
--- a/src/include/storage/pg_shmem.h
+++ b/src/include/storage/pg_shmem.h
@@ -39,15 +39,15 @@ typedef struct PGShmemHeader    /* standard header for all Postgres shmem */
 } PGShmemHeader;
 
 /* GUC variable */
-extern int huge_tlb_pages;
+extern int huge_pages;
 
-/* Possible values for huge_tlb_pages */
+/* Possible values for huge_pages */
 typedef enum
 {
-   HUGE_TLB_OFF,
-   HUGE_TLB_ON,
-   HUGE_TLB_TRY
-} HugeTlbType;
+   HUGE_PAGES_OFF,
+   HUGE_PAGES_ON,
+   HUGE_PAGES_TRY
+} HugePagesType;
 
 #ifndef WIN32
 extern unsigned long UsedShmemSegID;