From 8068de761facc5d887ddde880a33c3e45ad89854 Mon Sep 17 00:00:00 2001
From: Ulf Wendel <uw@php.net>
Date: Tue, 29 Jul 2014 19:54:42 +0000
Subject: [PATCH] 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               |  8 +++++---
 .../mysqlnd_ms/functions/mysqlnd-ms-xa-gc.xml   | 17 +++++++++++++++++
 reference/mysqlnd_ms/setup.xml                  |  3 +++
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml
index da834337b4..e907331fac 100755
--- a/reference/mysqlnd_ms/concepts.xml
+++ b/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>
diff --git a/reference/mysqlnd_ms/functions/mysqlnd-ms-xa-gc.xml b/reference/mysqlnd_ms/functions/mysqlnd-ms-xa-gc.xml
index 6afe475e95..55fa0d157d 100644
--- a/reference/mysqlnd_ms/functions/mysqlnd-ms-xa-gc.xml
+++ b/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>
 
diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml
index 6f5ba72eb8..aaee55bd49 100755
--- a/reference/mysqlnd_ms/setup.xml
+++ b/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>