From 0761e9d5e4a1130b2ed91b72fe661275f5ee6502 Mon Sep 17 00:00:00 2001
From: Ulf Wendel <uw@php.net>
Date: Thu, 14 Mar 2013 15:31:49 +0000
Subject: [PATCH] Final touches for alpha: trx detection improvements

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329786 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mysqlnd_ms/changes.xml    | 44 ++++++++++++++++++++++++++++-
 reference/mysqlnd_ms/concepts.xml   |  6 ++++
 reference/mysqlnd_ms/quickstart.xml |  6 ++++
 reference/mysqlnd_ms/setup.xml      | 10 +++++++
 4 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml
index 4b4f260f9e..e166a3d709 100644
--- a/reference/mysqlnd_ms/changes.xml
+++ b/reference/mysqlnd_ms/changes.xml
@@ -19,7 +19,7 @@
    <itemizedlist>
     <listitem>
      <simpara>
-      Release date: under development
+      Release date: 03/2013
      </simpara>
     </listitem>
     <listitem>
@@ -133,6 +133,48 @@
       but a failure to connect.
     </para>
     </listitem>
+    <listitem>
+     <para>
+      Improved transaction boundaries detection with PHP 5.5.0 or newer and
+      <literal>mysqli</literal>. The <literal>mysqli</literal> extension has been
+      modified to use new C API calls of the <literal>mysqlnd</literal>
+      library to begin, commit and rollback a transaction or savepoint.
+      If <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness"><literal>trx_stickiness</literal></link>
+      is used to enable transaction aware load balancing, not only the
+      <function>mysqli_autocommit</function> call will be monitored by the plugin
+      but also <function>mysqli_begin</function>, <function>mysqli_commit</function>
+      and <function>mysqli_rollback</function>. All SQL features to control
+      transactions are also available through the improved <literal>mysqli</literal>
+      transaction control related functions. Thus, there is no need to
+      issue SQL statements instead of using API calls. Applications
+      using the appropriate API calls only, can be load balanced by PECL/mysqlnd_ms
+      in a completely transaction aware way.
+     </para>
+     <para>
+      Please note, <literal>PDO_MySQL</literal> has not been updated
+      yet to utilize the new mysqlnd API calls. Thus, transaction boundary
+      detection with <literal>PDO_MySQL</literal> continues to be limited to
+      the monitoring of <function>PDO::setAttribute(PDO::ATTR_AUTOCOMMIT, ...)</function>.
+     </para>
+    </listitem>
+     <listitem>
+     <para>
+      Introduced <literal>trx_stickiness=on</literal>. This
+      <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness"><literal>trx_stickiness</literal></link>
+      option differs from <literal>trx_stickiness=master</literal> as it
+      tries to execute a read only transaction on a slave, if
+      quality of service (consistency level) allows the use of a slave.
+      Read only transactions have been introduced in MySQL 5.6. They
+      offer performance gains.
+     </para>
+    </listitem>
+    <listitem>
+      <para>
+       Query cache support considered beta if used with <literal>mysqli</literal>
+       API. It should work fine with primary copy based clusters. For all other
+       APIs, the feature continues to be called experimental.
+      </para>
+    </listitem>
     <listitem>
      <para>
       The code examples in the mysqlnd_ms source were updated.
diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml
index b5cea6244c..85bb7b5ccc 100755
--- a/reference/mysqlnd_ms/concepts.xml
+++ b/reference/mysqlnd_ms/concepts.xml
@@ -444,6 +444,12 @@
    sure that the autocommit settings is changed exclusively through the listed
    API calls.
   </para>
+  <para>
+   API based transaction boundary detection has been improved with PHP 5.5.0 and
+   PECL/mysqlnd_ms 1.5.0 to cover not only calls to <function>mysqli_autocommit</function>
+   but also <function>mysqli_begin</function>,
+   <function>mysqli_commit</function> and <function>mysqli_rollback</function>.
+  </para>
  </section>
 
  <section xml:id="mysqlnd-ms.errorhandling">
diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml
index 678258d101..f8a817b73b 100755
--- a/reference/mysqlnd_ms/quickstart.xml
+++ b/reference/mysqlnd_ms/quickstart.xml
@@ -728,6 +728,12 @@ $mysqli->close();
     the master. This prevents connection switches in the middle of
     a transaction. Once <literal>autocommit</literal> is re-enabled, the plugin
     starts to load balance statements again.
+  </para>
+   <para>
+   API based transaction boundary detection has been improved with PHP 5.5.0 and
+   PECL/mysqlnd_ms 1.5.0 to cover not only calls to <function>mysqli_autocommit</function>
+   but also <function>mysqli_begin</function>,
+   <function>mysqli_commit</function> and <function>mysqli_rollback</function>.
   </para>
   <para>
    <example>
diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml
index 8713cc1339..62f1c99bfc 100755
--- a/reference/mysqlnd_ms/setup.xml
+++ b/reference/mysqlnd_ms/setup.xml
@@ -2299,6 +2299,16 @@ $mysqli->set_charset("latin1");
        cannot be made aware of <literal>autocommit</literal> mode changes caused
        by SQL statements such as <literal>SET AUTOCOMMIT=0</literal> or <literal>BEGIN</literal>.
       </para>
+      <para>
+       Since PHP 5.5.0 the mysqlnd library features additional C API calls to
+       control transactions. The level of control matches the one offer by SQL
+       statement. The <literal>mysqli</literal> API has been modified to use
+       those calls. Since version 1.5.0, PECL/mysqlnd_ms can monitor not only
+       <function>mysqli_autocommit</function> but also <function>mysqli_begin</function>,
+       <function>mysqli_commit</function> and <function>mysqli_rollback</function> to
+       detect transaction boundaries and stop load balancing for the duration of
+       a transaction.
+      </para>
       <para>
        <example>
         <title>Using master to execute transactions</title>