From 5e3799d3171b02888602a968bbad9db413df3600 Mon Sep 17 00:00:00 2001
From: Ulf Wendel <uw@php.net>
Date: Wed, 20 Feb 2013 17:13:50 +0000
Subject: [PATCH] Document BC break and bug fix related to mysqlnd_ms_set_qos()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329523 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mysqlnd_ms/changes.xml                | 17 ++++++++++++++++-
 .../mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml |  8 +++++++-
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml
index 8a76a0fb20..16200725fe 100644
--- a/reference/mysqlnd_ms/changes.xml
+++ b/reference/mysqlnd_ms/changes.xml
@@ -72,13 +72,28 @@
       was combined it could happened that the SQL hints got ignored. In some
       case the SQL hints did work, in other cases they did not. The new
       behaviour is more consistent. SQL hints will always be ignore for
-      the duration of a transaction, if transaction stickiness is configured.
+      the duration of a transaction, if
+      <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness">transaction stickiness</link>
+      is enabled.
      </para>
      <para>
       Please note, transaction boundary detection continues to be based on API
       call monitoring. SQL commands controlling transactions are not monitored.
      </para>
     </listitem>
+    <listitem>
+     <para>
+      BC break and bug fix. Calls to <function>mysqlnd_ms_set_qos</function>
+      will fail when done in the middle of a transaction if
+      <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness">transaction stickiness</link>
+      is enabled. Connection switches are not allowed for the duration of a
+      transaction. Changing the quality of service likely results on a different
+      set of servers qualifying for query execution, possibly making it
+      necessary to switch connections. Thus, the call is not allowed in
+      during an active transaction. The quality of server can, however, be
+      changed in between transactions.
+     </para>
+    </listitem>
    </itemizedlist>
   </para>
   <para>
diff --git a/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml b/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml
index 73913fa1ff..bd53419933 100644
--- a/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml
+++ b/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml
@@ -48,6 +48,12 @@
    using <literal>master_on_write</literal>, which would continue using the master
    after the first write.
   </para>
+  <para>
+   Since 1.5.0 calls will fail when done in the middle of a transaction if
+   <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness">transaction stickiness</link>
+   is enabled and transaction boundaries have been detected.
+   properly.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -93,7 +99,7 @@
        <function>mysqlnd_ms_get_last_gtid</function>. If set, the
        plugin considers both master servers and asynchronous slaves for session
        consistency (read your writes). Otherwise, only masters are
-       used to achieve session consistency. A slave is considered up-to-date and 
+       used to achieve session consistency. A slave is considered up-to-date and
        checked if it has already replicated the global transaction ID from
        <parameter>option_value</parameter>. Please note, searching appropriate slaves
        is an expensive and slow operation. Use the feature sparsely, if the