docs - add content for lock_timeout guc (#7226)

* docs - add content for lock_timeout guc * add note about relationship to deadlock timeouts

docs - add content for lock_timeout guc (#7226)
* docs - add content for lock_timeout guc * add note about relationship to deadlock timeouts
3530d151 · Lisa Owen · David Yozie · 4eda66a8 · 3530d151 · 3530d151
4 changed file
--- a/gpdb-doc/dita/admin_guide/dml.xml
+++ b/gpdb-doc/dita/admin_guide/dml.xml
@@ -373,6 +373,13 @@
        detection. Because the local and global deadlock detection algorithms differ, the cancelled
        process(es) may differ depending upon which detector (local or global) Greenplum Database
        triggers first.</note>
+       <note>If the <codeph><xref
+            href="../ref_guide/config_params/guc-list.xml#lock_timeout" type="section"
+            >lock_timeout</xref></codeph> server configuration parameter
+         is turned on and set to a value smaller than <codeph>deadlock_timeout</codeph>
+         and <codeph>gp_global_deadlock_detector_period</codeph>, Greenplum Database
+         will abort a statement before it would ever trigger a deadlock check in that
+         session.</note>
      <p>To view lock waiting information for all segments, run the
          <codeph>pg_dist_wait_status()</codeph> user-defined function. You can use the output of
        this function to determine which transactions are waiting on locks, which transactions are

--- a/gpdb-doc/dita/ref_guide/config_params/guc-list.xml
+++ b/gpdb-doc/dita/ref_guide/config_params/guc-list.xml
@@ -475,6 +475,9 @@
            <li>
              <xref href="#local_preload_libraries"/>
            </li>
+            <li>
+              <xref href="#lock_timeout"/>
+            </li>
            <li>
              <xref href="#log_autostats"/>
            </li>
@@ -5865,6 +5868,55 @@
      </table>
    </body>
  </topic>
+  <topic id="lock_timeout">
+    <title>lock_timeout</title>
+    <body>
+      <p>Abort any statement that waits longer than the specified number of
+        milliseconds while attempting to acquire a lock on a table, index,
+        row, or other database object. The time limit applies separately to
+        each lock acquisition attempt. The limit applies both to explicit
+        locking requests (such as <codeph>LOCK TABLE</codeph>, or
+        <codeph>SELECT FOR UPDATE</codeph> without <codeph>NOWAIT</codeph>)
+        and to implicitly-acquired locks. If <codeph>log_min_error_statement</codeph>
+        is set to <codeph>ERROR</codeph> or lower, Greenplum Database logs the
+        statement that timed out. A value of zero (the default) turns off this 
+        lock wait monitoring.</p>
+      <p>Unlike <codeph><xref href="#statement_timeout" format="dita"/></codeph>,
+        this timeout can only occur while waiting for locks. Note that if
+        <codeph>statement_timeout</codeph> is nonzero, it is rather pointless
+        to set <codeph>lock_timeout</codeph> to the same or larger value,
+        since the statement timeout would always trigger first.</p>
+      <p>Greenplum Database uses the <codeph><xref href="#deadlock_timeout" format="dita"/></codeph>
+        and <codeph><xref href="#gp_global_deadlock_detector_period" format="dita"/></codeph>
+        to trigger local and global deadlock detection. Note that if <codeph>lock_timeout</codeph>
+        is turned on and set to a value smaller than these deadlock detection
+        timeouts, Greenplum Database will abort a statement before it would 
+        ever trigger a deadlock check in that session.</p>
+      <note>Setting <codeph>lock_timeout</codeph> in <codeph>postgresql.conf</codeph>
+        is not recommended because it would affect all sessions</note>
+      <table id="lock_timeout_table">
+        <tgroup cols="3">
+          <colspec colnum="1" colname="col1" colwidth="1*"/>
+          <colspec colnum="2" colname="col2" colwidth="1*"/>
+          <colspec colnum="3" colname="col3" colwidth="1*"/>
+          <thead>
+            <row>
+              <entry colname="col1">Value Range</entry>
+              <entry colname="col2">Default</entry>
+              <entry colname="col3">Set Classifications</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry colname="col1">0 - <codeph>INT_MAX</codeph> millisecs</entry>
+              <entry colname="col2">0 millisecs</entry>
+              <entry colname="col3">master<p>session</p><p>reload</p></entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </body>
+  </topic>
  <topic id="log_autostats">
    <title>log_autostats</title>
    <body>

--- a/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml
+++ b/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml
@@ -1068,6 +1068,10 @@
            </p>
          </stentry>
          <stentry>
+            <p>
+              <xref href="guc-list.xml#lock_timeout" type="section"
+                >lock_timeout</xref>
+            </p>
            <p>
              <xref href="guc-list.xml#max_locks_per_transaction" type="section"
                >max_locks_per_transaction</xref>

--- a/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap
+++ b/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap
@@ -184,6 +184,7 @@
            <topicref href="guc-list.xml#lc_time"/>
            <topicref href="guc-list.xml#listen_addresses"/>
            <topicref href="guc-list.xml#local_preload_libraries"/>
+            <topicref href="guc-list.xml#lock_timeout"/>
            <topicref href="guc-list.xml#log_autostats"/>
            <topicref href="guc-list.xml#log_connections"/>
            <topicref href="guc-list.xml#log_disconnections"/>