From 55aa04cff2695193f9add5ab37a165f4de7f32ff Mon Sep 17 00:00:00 2001
From: Ulf Wendel <uw@php.net>
Date: Tue, 27 Sep 2011 14:21:00 +0000
Subject: [PATCH] 1.1.0 update: a few more words on load balancing, nothing
 really new. Additional minor updates.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317396 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mysqlnd_ms/concepts.xml | 59 +++++++++++++++++--------------
 1 file changed, 33 insertions(+), 26 deletions(-)

diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml
index 2b062af214..c77216d223 100755
--- a/reference/mysqlnd_ms/concepts.xml
+++ b/reference/mysqlnd_ms/concepts.xml
@@ -7,13 +7,13 @@
   The concept section explains the overall architecture and important concepts
   of the plugin. The materials aim to help you understanding the impact of
   MySQL replication and using the plugin for your development tasks.
-  Any application using MySQL Replication must take care of certain tasks that
+  Any application using MySQL replication must take care of certain tasks that
   arise from using a database cluster.
  </para>
  <para>
   It is strongly recommended to work through the materials in order to
   be able to use the plugin with success. This is particulary true, if you are
-  new to using MySQL Replication.
+  new to using MySQL replication.
  </para>
  <section xml:id="mysqlnd-ms.architecture">
   <title>Architecture</title>
@@ -277,7 +277,7 @@
    <quote>remember</quote> all settings to apply them on connections
    opened in the future. This is important to remember, if
    using
-   <link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link>.
+   <link linkend="ini.mysqlnd-ms-plugin-config-v2.lazy_connections">lazy connections</link>.
    Lazy connections are connections which are not
    opened before the client sends the first connection.
    Use of lazy connections is the default plugin action.
@@ -424,7 +424,7 @@
   <para>
     The failover policy is configured in the plugins configuration file by help
     of the
-    <literal><link linkend="ini.mysqlnd-ms-plugin-config.failover">failover</link></literal>
+    <literal><link linkend="ini.mysqlnd-ms-plugin-config-v2.failover">failover</link></literal>
     configuration directive.
   </para>
  </section>
@@ -433,19 +433,27 @@
   <title>Load balancing</title>
   <para>
     Four load balancing strategies are supported to distribute read-only
-    statements over the configured MySQL slave servers:
-    <literal>random</literal>, <literal>random_once</literal> (default),
-    <literal>roundrobin</literal>, <literal>user</literal>.
+    statements over the configured MySQL slave servers: random, random once,
+    round robin and user defined via callback. Random picks a random
+    server whenever a statement is to be executed. Random once picks a
+    random server once when the first statement is executed and uses
+    the decision for the rest of the PHP request. Random once is the default,
+    if nothing else is configured because random once has the lowest impact
+    on the connection state. Round robin iterates over the list of
+    configured servers. A user defined callback can be used to implement
+    any other strategy.
   </para>
   <para>
     The load balancing policy is configured in the plugins configuration
     file using the
-    <link linkend="ini.mysqlnd-ms-plugin-config.pick">pick[]</link>
-    configuration directive.
+    <link linkend="ini.mysqlnd-ms-plugin-config-v2.filter_random">random</link>,
+    <link linkend="ini.mysqlnd-ms-plugin-config-v2.filter_roundrobin">roundrobin</link>
+    and <link linkend="ini.mysqlnd-ms-plugin-config-v2.filter_user">user</link>
+    filter. Please, see below to learn more about
+    <link linkend="mysqlnd-ms.filter">filter</link>.
   </para>
  </section>
 
-
  <section xml:id="mysqlnd-ms.rwsplit">
   <title>Read-write splitting</title>
   <para>
@@ -487,15 +495,14 @@
   </note>
  </section>
 
-<section xml:id="mysqlnd-ms.filter">
+ <section xml:id="mysqlnd-ms.filter">
   <title>Filter</title>
-
- <note>
-   <para>
-    The below description applies to PECL/mysqlnd_ms &gt;= 1.1.0-beta.
-    It is not valid for earlier versions.
-   </para>
-  </note>
+  <note>
+    <para>
+     The below description applies to PECL/mysqlnd_ms &gt;= 1.1.0-beta.
+     It is not valid for earlier versions.
+    </para>
+   </note>
   <para>
    PECL/mysqlnd 1.1.0-beta introduces the concept of
    <link linkend="mysqlnd-ms.plugin-ini-json">filters</link>.
@@ -503,8 +510,8 @@
    a group of servers in the cluster which could execute a given statement before
    the statement is executed on one of the candidates. In other words: a given
    list of servers has to be filtered until one server is left.
- </para>
- <para>
+  </para>
+  <para>
    The process of filtering may include the use one or more filters. Filters can be
    chained. They are executed in the order of their appearance in the plugins
    configuration file. The concept of chained filters can be compared to using
@@ -528,10 +535,10 @@
       Selection filter:
       <link linkend="ini.mysqlnd-ms-plugin-config-v2.filters"><literal>user</literal></link>.
      </simpara>
-   </listitem>
+    </listitem>
    </itemizedlist>
- </para>
- <para>
+  </para>
+  <para>
    The <literal>random</literal> and <literal>roundrobin</literal>
    filters replace the
    <link linkend="ini.mysqlnd-ms-plugin-config.pick"><literal>pick[]</literal></link>
@@ -548,7 +555,7 @@
    Filters can accept parameters to change their behaviour.
    The <literal>random</literal> filter accepts an optional
    <literal>sticky</literal> parameter. If set to true, the filter chnages
-   load balancing from random to random once. Random picks a random server
+  load balancing from random to random once. Random picks a random server
    every time a statement is to be executed. Random once picks a random
    server when the first statement is to be executed and uses the same
    server for the rest of the PHP request.
@@ -607,7 +614,7 @@
   <para>
    In future versions there may be filters which return more than one candidate
    for statement execution. For example, there may be a <literal>table</literal>
-   filter to support MySQL Replication filtering. MySQL replication filter allow
+   filter to support MySQL replication filtering. MySQL replication filter allow
    you to define rules which database or table is to be replicated to which
    node of a replication cluster. Assume your replication cluster
    consists of four slaves (<literal>slave_0</literal>, <literal>slave_1</literal>,
@@ -622,7 +629,7 @@
   </para>
   <para>
    A hypothetical filter sequence, assuming the existance of a <literal>table</literal>
-   filter to support MySQL Replication filtering (client-side partitioning).
+   filter to support MySQL replication filtering (client-side partitioning).
    <itemizedlist>
     <listitem>
      <simpara>