Add GUC and storage parameter to set the maximum size of GIN pending list.

Previously the maximum size of GIN pending list was controlled only by
work_mem. But the reasonable value of work_mem and the reasonable size
of the list are basically not the same, so it was not appropriate to
control both of them by only one GUC, i.e., work_mem. This commit
separates new GUC, pending_list_cleanup_size, from work_mem to allow
users to control only the size of the list.

Also this commit adds pending_list_cleanup_size as new storage parameter
to allow users to specify the size of the list per index. This is useful,
for example, when users want to increase the size of the list only for
the GIN index which can be updated heavily, and decrease it otherwise.

Reviewed by Etsuro Fujita.

5 files changed, 58 insertions, 18 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 47b11922455..6bfb7bbc112 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -5911,6 +5911,27 @@ SET XML OPTION { DOCUMENT | CONTENT };
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-pending-list-cleanup-size" xreflabel="pending_list_cleanup_size">
+      <term><varname>pending_list_cleanup_size</varname> (<type>integer</type>)
+      <indexterm>
+       <primary><varname>pending_list_cleanup_size</> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Sets the maximum size of the GIN pending list which is used
+        when <literal>fastupdate</> is enabled. If the list grows
+        larger than this maximum size, it is cleaned up by moving
+        the entries in it to the main GIN data structure in bulk.
+        The default is four megabytes (<literal>4MB</>). This setting
+        can be overridden for individual GIN indexes by changing
+        storage parameters.
+         See <xref linkend="gin-fast-update"> and <xref linkend="gin-tips">
+         for more information.
+       </para>
+      </listitem>
+     </varlistentry>
+
      </variablelist>
     </sect2>
      <sect2 id="runtime-config-client-format">
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index 8443c01f6f7..94d2d5c19d9 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -728,8 +728,8 @@
    from the indexed item). As of <productname>PostgreSQL</productname> 8.4,
    <acronym>GIN</> is capable of postponing much of this work by inserting
    new tuples into a temporary, unsorted list of pending entries.
-   When the table is vacuumed, or if the pending list becomes too large
-   (larger than <xref linkend="guc-work-mem">), the entries are moved to the
+   When the table is vacuumed, or if the pending list becomes larger than
+   <xref linkend="guc-pending-list-cleanup-size">, the entries are moved to the
    main <acronym>GIN</acronym> data structure using the same bulk insert
    techniques used during initial index creation.  This greatly improves
    <acronym>GIN</acronym> index update speed, even counting the additional
@@ -750,7 +750,7 @@
   <para>
    If consistent response time is more important than update speed,
    use of pending entries can be disabled by turning off the
-   <literal>FASTUPDATE</literal> storage parameter for a
+   <literal>fastupdate</literal> storage parameter for a
    <acronym>GIN</acronym> index.  See <xref linkend="sql-createindex">
    for details.
   </para>
@@ -812,18 +812,26 @@
   </varlistentry>
 
   <varlistentry>
-   <term><xref linkend="guc-work-mem"></term>
+   <term><xref linkend="guc-pending-list-cleanup-size"></term>
    <listitem>
     <para>
      During a series of insertions into an existing <acronym>GIN</acronym>
-     index that has <literal>FASTUPDATE</> enabled, the system will clean up
+     index that has <literal>fastupdate</> enabled, the system will clean up
      the pending-entry list whenever the list grows larger than
-     <varname>work_mem</>.  To avoid fluctuations in observed response time,
-     it's desirable to have pending-list cleanup occur in the background
-     (i.e., via autovacuum).  Foreground cleanup operations can be avoided by
-     increasing <varname>work_mem</> or making autovacuum more aggressive.
-     However, enlarging <varname>work_mem</> means that if a foreground
-     cleanup does occur, it will take even longer.
+     <varname>pending_list_cleanup_size</>. To avoid fluctuations in observed
+     response time, it's desirable to have pending-list cleanup occur in the
+     background (i.e., via autovacuum).  Foreground cleanup operations
+     can be avoided by increasing <varname>pending_list_cleanup_size</>
+     or making autovacuum more aggressive.
+     However, enlarging the threshold of the cleanup operation means that
+     if a foreground cleanup does occur, it will take even longer.
+    </para>
+    <para>
+     <varname>pending_list_cleanup_size</> can be overridden for individual
+     GIN indexes by changing storage parameters, and which allows each
+     GIN index to have its own cleanup threshold.
+     For example, it's possible to increase the threshold only for the GIN
+     index which can be updated heavily, and decrease it otherwise.
     </para>
    </listitem>
   </varlistentry>
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 0158b1759e8..5de282b2948 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -861,7 +861,7 @@ my_distance(PG_FUNCTION_ARGS)
   <para>
    By default, a GiST index build switches to the buffering method when the
    index size reaches <xref linkend="guc-effective-cache-size">. It can
-   be manually turned on or off by the <literal>BUFFERING</literal> parameter
+   be manually turned on or off by the <literal>buffering</literal> parameter
    to the CREATE INDEX command. The default behavior is good for most cases,
    but turning buffering off might speed up the build somewhat if the input
    data is ordered.
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 2ab090d03e5..e6a77095ec3 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -46,7 +46,7 @@ CLUSTER [VERBOSE]
    not clustered.  That is, no attempt is made to store new or
    updated rows according to their index order.  (If one wishes, one can
    periodically recluster by issuing the command again.  Also, setting
-   the table's <literal>FILLFACTOR</literal> storage parameter to less than
+   the table's <literal>fillfactor</literal> storage parameter to less than
    100% can aid in preserving cluster ordering during updates, since updated
    rows are kept on the same page if enough space is available there.)
   </para>
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 18bd0d33704..21f7604ac08 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -300,7 +300,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
 
    <variablelist>
    <varlistentry>
-    <term><literal>FILLFACTOR</></term>
+    <term><literal>fillfactor</></term>
     <listitem>
      <para>
       The fillfactor for an index is a percentage that determines how full
@@ -327,7 +327,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
 
    <variablelist>
    <varlistentry>
-    <term><literal>BUFFERING</></term>
+    <term><literal>buffering</></term>
     <listitem>
     <para>
      Determines whether the buffering build technique described in
@@ -341,12 +341,12 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
    </variablelist>
 
    <para>
-    GIN indexes accept a different parameter:
+    GIN indexes accept different parameters:
    </para>
 
    <variablelist>
    <varlistentry>
-    <term><literal>FASTUPDATE</></term>
+    <term><literal>fastupdate</></term>
     <listitem>
     <para>
      This setting controls usage of the fast update technique described in
@@ -359,7 +359,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
 
     <note>
      <para>
-      Turning <literal>FASTUPDATE</> off via <command>ALTER INDEX</> prevents
+      Turning <literal>fastupdate</> off via <command>ALTER INDEX</> prevents
       future insertions from going into the list of pending index entries,
       but does not in itself flush previous entries.  You might want to
       <command>VACUUM</> the table afterward to ensure the pending list is
@@ -369,6 +369,17 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
     </listitem>
    </varlistentry>
    </variablelist>
+   <variablelist>
+   <varlistentry>
+    <term><literal>pending_list_cleanup_size</></term>
+    <listitem>
+    <para>
+     Custom <xref linkend="guc-pending-list-cleanup-size"> parameter.
+     This value is specified in kilobytes.
+    </para>
+    </listitem>
+   </varlistentry>
+   </variablelist>
   </refsect2>
 
   <refsect2 id="SQL-CREATEINDEX-CONCURRENTLY">