Third parameter for mysqlnd_ms_xa_gc to force GC runs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@334415 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mysqlnd_ms/concepts.xml

@@ -2312,12 +2312,14 @@ mysqlnd_ms_xa_commit($link, 1);
   <para>
     For each failed XA transaction the garbage collection makes
     <literal>max_retries</literal> (default: 5) attempts to finish it. After that
-    <literal>PECL/mysqlnd_ms</literal> gives up and the XA transaction must be
-    cleaned up by a human operator. There are two possible reasons for this. Either
+    <literal>PECL/mysqlnd_ms</literal> gives up. There are two possible reasons for this. Either
     a participating server crashed and has not become accessible again within
     <literal>max_retries</literal> invocations of the garbage collection, or there
     is a situation that the built-in garbage collection cannot cope with. Likely, the
-    latter would be considered a bug.
+    latter would be considered a bug. However, you can manually force more
+    garbage collection runs calling <function>mysqlnd_ms_xa_gc</function> with the
+    appropriate parameter set. Should even those function runs fail to solve
+    the situation, then the problem must be solved by an operator.
   </para>
   <para>
     The function <link linkend="function.mysqlnd-ms-get-stats"><function>mysqlnd_ms_get_stats</function></link>

reference/mysqlnd_ms/functions/mysqlnd-ms-xa-gc.xml

@@ -14,6 +14,8 @@
    <methodname>mysqlnd_ms_xa_gc</methodname>
    <methodparam><type>mixed</type><parameter>connection</parameter></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>gtrid</parameter></methodparam>
+   <methodparam choice="opt"><type>boolean</type><parameter>ignore_max_retries</parameter></methodparam>
+
 
   </methodsynopsis>
   <para>
@@ -77,6 +79,21 @@
      </para>
     </listitem>
    </varlistentry>
+    <varlistentry>
+    <term><parameter>ignore_max_retries</parameter></term>
+    <listitem>
+     <para>
+      Whether to ignore the plugin configuration <literal>max_retries</literal> setting.
+      If garbage collection continously fails and the <literal>max_retries</literal>
+      limit is reached prior to finishing the failed global transaction,
+      you can attempt further runs prior to investigating the cause
+      and solving the issue manually by issueing appropriate SQL statements
+      on the participants. Setting the parameter has the same effect
+      as temporarily setting <literal>max_retries = 0</literal>.
+     </para>
+    </listitem>
+   </varlistentry>
+
   </variablelist>
  </refsect1>
 

reference/mysqlnd_ms/setup.xml

@@ -3034,6 +3034,9 @@ CREATE TABLE mysqlnd_ms_xa_gc (
                long as crashed servers become available again quickly.
                Still, a situation may arise where a human is required to
                act because the built-in garbage collection stopped or failed.
+               In this case, you may first want to check if the transaction still
+               cannot be fixed by forcing <function>mysqlnd_ms_xa_gc</function>
+               to ignore the setting, prior to handling it manually.
               </para>
               <para>
                Default: <literal>5</literal>