Doc: improve descriptions of max_[pred_]locks_per_transaction GUCs.

The old wording described these as being multiplied by max_connections
plus max_prepared_transactions, which hasn't been exactly right for
some time thanks to the addition of various auxiliary processes.
Moreover, exactness here is a bit pointless given that the lock tables
can expand into the initially-unallocated "slop" space in shared
memory.  Rather than trying to track exactly what the code is doing,
let's just use the term "server processes".

Likewise adjust these GUCs' description strings in guc_tables.c.

Wang Wei, reviewed by Nathan Bossart and myself

Discussion: https://postgr.es/m/OS3PR01MB6275BDD09C9B875C65FCC5AB9EA39@OS3PR01MB6275.jpnprd01.prod.outlook.com

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 25111d5caf3bd613ae88010dfe9652476f30f070..2762290465431e7276d9bcf3b56f04d46abe55fe 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -10236,13 +10236,12 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </term>
       <listitem>
        <para>
-        The shared lock table tracks locks on
-        <varname>max_locks_per_transaction</varname> * (<xref
-        linkend="guc-max-connections"/> + <xref
-        linkend="guc-max-prepared-transactions"/>) objects (e.g.,  tables);
+        The shared lock table has space for
+        <varname>max_locks_per_transaction</varname> objects
+        (e.g., tables) per server process or prepared transaction;
         hence, no more than this many distinct objects can be locked at
-        any one time.  This parameter controls the average number of object
-        locks allocated for each transaction;  individual transactions
+        any one time.  This parameter limits the average number of object
+        locks used by each transaction; individual transactions
         can lock more objects as long as the locks of all transactions
         fit in the lock table.  This is <emphasis>not</emphasis> the number of
         rows that can be locked; that value is unlimited.  The default,
@@ -10253,8 +10252,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
        </para>
 
        <para>
-        When running a standby server, you must set this parameter to the
-        same or higher value than on the primary server. Otherwise, queries
+        When running a standby server, you must set this parameter to have the
+        same or higher value as on the primary server. Otherwise, queries
         will not be allowed in the standby server.
        </para>
       </listitem>
@@ -10268,17 +10267,16 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </term>
       <listitem>
        <para>
-        The shared predicate lock table tracks locks on
-        <varname>max_pred_locks_per_transaction</varname> * (<xref
-        linkend="guc-max-connections"/> + <xref
-        linkend="guc-max-prepared-transactions"/>) objects (e.g., tables);
+        The shared predicate lock table has space for
+        <varname>max_pred_locks_per_transaction</varname> objects
+        (e.g., tables) per server process or prepared transaction;
         hence, no more than this many distinct objects can be locked at
-        any one time.  This parameter controls the average number of object
-        locks allocated for each transaction;  individual transactions
+        any one time.  This parameter limits the average number of object
+        locks used by each transaction; individual transactions
         can lock more objects as long as the locks of all transactions
         fit in the lock table.  This is <emphasis>not</emphasis> the number of
         rows that can be locked; that value is unlimited.  The default,
-        64, has generally been sufficient in testing, but you might need to
+        64, has historically proven sufficient, but you might need to
         raise this value if you have clients that touch many different
         tables in a single serializable transaction. This parameter can
         only be set at server start.

diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index e8e8245e91ff95e11c0469909d7508df08fc8acd..cf7f465ddb15a720fc39b70ea57eb60301c9a6cb 100644 (file)
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2599,9 +2599,9 @@ struct config_int ConfigureNamesInt[] =
    {
        {"max_locks_per_transaction", PGC_POSTMASTER, LOCK_MANAGEMENT,
            gettext_noop("Sets the maximum number of locks per transaction."),
-           gettext_noop("The shared lock table is sized on the assumption that "
-                        "at most max_locks_per_transaction * max_connections distinct "
-                        "objects will need to be locked at any one time.")
+           gettext_noop("The shared lock table is sized on the assumption that at most "
+                        "max_locks_per_transaction objects per server process or prepared "
+                        "transaction will need to be locked at any one time.")
        },
        &max_locks_per_xact,
        64, 10, INT_MAX,
@@ -2612,8 +2612,8 @@ struct config_int ConfigureNamesInt[] =
        {"max_pred_locks_per_transaction", PGC_POSTMASTER, LOCK_MANAGEMENT,
            gettext_noop("Sets the maximum number of predicate locks per transaction."),
            gettext_noop("The shared predicate lock table is sized on the assumption that "
-                        "at most max_pred_locks_per_transaction * max_connections distinct "
-                        "objects will need to be locked at any one time.")
+                        "at most max_pred_locks_per_transaction objects per server process "
+                        "or prepared transaction will need to be locked at any one time.")
        },
        &max_predicate_locks_per_xact,
        64, 10, INT_MAX,