Brief description of the new constants related to mysqlnd_ms_set_qos()

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

reference/mysqlnd_ms/concepts.xml

@@ -966,6 +966,8 @@ version = 5.6.2-m5-log
    <title>Version requirement</title>
    <para>
     Service levels have been introduced in mysqlnd_ms version 1.2.0-alpha.
+    <link linkend="function.mysqlnd-ms-set-qos"><function>mysqlnd_ms_set_qos</function></link>
+    requires PHP 5.4.0 or newer.
    </para>
   </note>
   <para>
@@ -988,7 +990,8 @@ version = 5.6.2-m5-log
   <para>
    Service levels can be set through the qualify-of-service filter in the
    <link linkend="mysqlnd-ms.plugin-ini-json">plugins configuration file</link>
-   and at runtime using the function <literal>mysqlnd_ms_set_qos()</literal>.
+   and at runtime using the function
+   <link linkend="function.mysqlnd-ms-set-qos"><function>mysqlnd_ms_set_qos</function></link>.
   </para>
   <para>
    The plugin defines the different service levels as follows.

reference/mysqlnd_ms/constants.xml

@@ -12,7 +12,7 @@
   <example>
    <para>
     The mysqlnd replication and load balancing plugin (<literal>mysqlnd_ms</literal>)
-    performs read/write splitting. This directs write queries to a MySQL 
+    performs read/write splitting. This directs write queries to a MySQL
     master server, and read-only queries to the MySQL slave servers.
     The plugin has a built-in read/write split logic.
     All queries which start with <literal>SELECT</literal> are considered read-only
@@ -104,7 +104,8 @@ slave_query = /*ms=slave*/SHOW TABLES
  </para>
 
  <para>
-  <function>mysqlnd_ms_is_select</function> related
+  <link linkend="function.mysqlnd-ms-query-is-select"><function>mysqlnd_ms_query_is_select</function></link>
+  related
  </para>
  <para>
   <variablelist>
@@ -153,6 +154,84 @@ slave_query = /*ms=slave*/SHOW TABLES
   </variablelist>
  </para>
 
+ <para>
+  <link linkend="function.mysqlnd-ms-set-qos"><function>mysqlnd_ms_set_qos</function></link>,
+  quality of service filter and service level related
+ </para>
+ <para>
+  <variablelist>
+   <varlistentry>
+    <term>
+     <constant>MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Use to request the service level eventual consistency from the
+      <function>mysqlnd_ms_set_qos</function>. Eventual consistency is the
+      default quality of service when reading from an asynchronous MySQL
+      replication slave. Data returned in this service level may or may not
+      be stale, depending on whether the selected slaves happens to have replicated
+      the lastest changes from the MySQL replication master or not.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <constant>MYSQLND_MS_QOS_CONSISTENCY_SESSION</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Use to request the service level session consistency from the
+      <function>mysqlnd_ms_set_qos</function>. Session consistency
+      is defined as read your writes. The client is guaranteed to see his
+      latest changes.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <constant>MYSQLND_MS_QOS_CONSISTENCY_STRONG</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Use to request the service level strong consistency from the
+      <function>mysqlnd_ms_set_qos</function>. Strong consistency
+      is used to ensure all clients see each others changes.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <constant>MYSQLND_MS_QOS_OPTION_GTID</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Used as a service level option with
+      <function>mysqlnd_ms_set_qos</function> to parameterize session
+      consistency.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <constant>MYSQLND_MS_QOS_OPTION_AGE</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Used as a service level option with
+      <function>mysqlnd_ms_set_qos</function> to parameterize eventual
+      consistency.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </para>
+
  <para>
   <emphasis role="bold">Other</emphasis>
  </para>

reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml

@@ -108,7 +108,7 @@
        which <literal>SHOW SLAVE STATUS</literal> reports
        <literal>Slave_IO_Running=Yes</literal>,
        <literal>Slave_SQL_Running=Yes</literal> and
-       <literal>Seconds_Behind_Master &lt;option_value</literal>. Please note,
+       <literal>Seconds_Behind_Master &lt;= option_value</literal>. Please note,
        searching appropriate slaves is an expensive and slow operation.
        Use the feature sparsely in version 1.2.0. Future versions may improve the
        algorithm used to identify candidates. Please, see the MySQL reference

reference/mysqlnd_ms/quickstart.xml

@@ -783,6 +783,8 @@ $mysqli->close();
    <title>Version requirement</title>
    <para>
     Service levels have been introduced in mysqlnd_ms version 1.2.0-alpha.
+    <link linkend="function.mysqlnd-ms-set-qos"><function>mysqlnd_ms_set_qos</function></link>
+    is available with PHP 5.4.0 or newer.
    </para>
   </note>
   <para>
@@ -871,7 +873,8 @@ if (!$res = $mysqli->query("SELECT item, price FROM specials"))
   </para>
   <para>
    Service levels can be set in the plugins configuration file and at runtime
-   using mysqlnd_ms_set_qos(). In the example the function is used to enforce
+   using <link linkend="function.mysqlnd-ms-set-qos"><function>mysqlnd_ms_set_qos</function></link>.
+   In the example the function is used to enforce
    session consistency (read your writes) for all future statements until further notice.
    The <literal>SELECT</literal> statement on the <literal>orders</literal> table
    is run on the master to ensure the previous write can be seen by the client.
@@ -1088,7 +1091,7 @@ PHP Warning:  mysqli::query(): (mysqlnd_ms) No connection selected by the last f
    the change already. Read load is taken away from the master.
   </para>
   <para>
-   Client-side global transaction ID injection has some limitations. Please,
+   Client-side global transaction ID emulation has some limitations. Please,
    read the <link linkend="mysqlnd-ms.gtid">concepts section</link>
    carefully to fully understand the principles and ideas
    behind it, before using in production environments. The background knowledge
@@ -1378,7 +1381,8 @@ var_dump($res->fetch_assoc());
    A GTID returned from <literal>mysqlnd_ms_get_last_gtid()</literal>
    can be used as an option for the session consistency service level.
    Session consistency delivers read your writes. Session consistency can
-   be requested by calling <literal>mysqlnd_ms_set_qos()</literal>.
+   be requested by calling
+   <link linkend="function.mysqlnd-ms-set-qos"><function>mysqlnd_ms_set_qos</function></link>.
    In the example, the plugin will execute the <literal>SELECT</literal>
    statement either on the master or on a slave which has replicated
    the previous <literal>INSERT</literal> already.