diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml
index 3ad8ee0527..f544ac3246 100755
--- a/reference/mysqlnd_ms/concepts.xml
+++ b/reference/mysqlnd_ms/concepts.xml
@@ -814,7 +814,7 @@ version = 5.6.2-m5-log
load balancing policies. The 'round robin' load balancing can be configured
through the roundrobin filter. Setting a 'user defined
callback' for server selection is possible with the user
- filter. The qos (quality-of-service) filter finds cluster
+ filter. The quality_of_service filter finds cluster
nodes capable of delivering a certain service, for example, read-your-writes or,
not lagging more seconds behind the master than allowed.
@@ -880,7 +880,7 @@ version = 5.6.2-m5-log
A second type of filter exists: multi filter. A multi filter emits zero, one or multiple
- servers after processing. The qos (quality-of-service) filter
+ servers after processing. The quality_of_service filter
is an example. If the service quality requested sets an upper limit for the slave
lag and more than one slave is lagging behind less than the allowed number of seconds,
the filter returns more than one cluster node. A multi filter must be followed by other
@@ -888,7 +888,7 @@ version = 5.6.2-m5-log
is found.
- A filter sequence with the qos (quality-of-service)
+ A filter sequence with the quality_of_service
multi filter followed by a load balancing filter.
@@ -907,7 +907,7 @@ version = 5.6.2-m5-log
- Filter: qos, rule set: read-your-writes
+ Filter: quality_of_service, rule set: session_consistency (read-your-writes)
Output: master_0
diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml
index 3174cde4d3..ed67d1f21c 100755
--- a/reference/mysqlnd_ms/setup.xml
+++ b/reference/mysqlnd_ms/setup.xml
@@ -1119,19 +1119,19 @@ User has connected to 'myapp'...
- Filter: qos
+ Filter: quality_of_serviceobject
- The quality-of-service (qos) filter identifies cluster nodes
+ The quality_of_service identifies cluster nodes
capable of delivering a certain quality of service. It is a multi filter
which returns zero, one or multiple of its input servers. Thus, it
must be followed by other filters to reduce the number of candidates
down to one for statement execution.
- The qos filter has been introduced in 1.2.0-alpha.
+ The quality_of_service filter has been introduced in 1.2.0-alpha.
In the 1.2 series the filters focus is on the consistency aspect of
service quality. Different types of clusters offer different
default data consistencies. For example, an asynchronous MySQL
@@ -1140,15 +1140,25 @@ User has connected to 'myapp'...
it may serve stale database because its lagging behind or it may serve
current information. Often, this is acceptable. In some cases
higher consistency levels are needed for the application to work correct.
- In those cases, the qos can filter out cluster nodes
+ In those cases, the quality_of_service can filter out cluster nodes
which cannot deliver the necessary quality of service.
- The qos filter can be replaced
+ The quality_of_service filter can be replaced or created
at runtime. A successful call to
mysqlnd_ms_set_qos
removes all existing qos filter entries from the
- filter list and installs a new one at the very beginning.
+ filter list and installs a new one at the very beginning. All settings
+ that can be made through
+ mysqlnd_ms_set_qos
+ can also be in the plugins configuration file. However, use of the function
+ is by far the most common use case. Instead of setting session consistency and
+ strong consistency service levels in the plugins configuration file it is
+ recommended to define only masters and no slaves. Both service levels will
+ force the use of masters only. Using an empty slave list shortens the
+ configuration file, thus improving readability. The only service level for which
+ there is a case of defining in the plugins configuration file is the combination
+ of eventual consistency and maximum slave lag.
@@ -1172,6 +1182,57 @@ User has connected to 'myapp'...
Request eventual consistency. Allows the use of all
master and slave servers. Data returned may or may not be current.
+
+ Eventual consistency accepts an optional age
+ parameter. If age is given the plugin considers
+ only slaves for reading for which MySQL replication reports
+ a slave lag less or equal to age.
+ The repliation lag is measure using SHOW SLAVE STATUS.
+ If the plugin fails to fetch the replication lag, the slave tested
+ is skipped. Implementation details and tipps are given in the
+ quality of service concepts section.
+
+
+ Please note, if a filter chain
+ generates an empty slave list and the PHP configuration directive
+ mysqlnd_ms.multi_master=0 is used, the plugin may
+ emit a warning.
+
+
+
+ Global limit on slave lag
+
+
+
+
+ Since 1.2.0.
@@ -1376,7 +1437,7 @@ User has connected to 'myapp'...
- Please, note the qos (quality of service) filter introduced
+ Please, note the quality_of_service filter introduced
in version 1.2.0-alpha. It gives finer control, for example, for achieving read-your-writes
and, it offers additional functionality introducing
service levels.