sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Quality of service filter docs

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321162 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel 2011-12-19 14:31:10 +00:00
parent 5155297701
commit fa611d7b25
2 changed files with 179 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

147
reference/mysqlnd_ms/concepts.xml
View file

@ -802,34 +802,21 @@ version = 5.6.2-m5-log
<listitem>
<simpara>
Selection filter:
<link linkend="ini.mysqlnd-ms-plugin-config-v2.filters">user</link>.
<link linkend="ini.mysqlnd-ms-plugin-config-v2.filters">user</link>,
<link linkend="ini.mysqlnd-ms-plugin-config-v2.filters">quality-of-service (qos)</link>.
</simpara>
</listitem>
</itemizedlist>
</para>
<note>
<title>pick[] versus filters</title>
<para>
The <literal>random</literal> and <literal>roundrobin</literal>
filters replace the
<link linkend="ini.mysqlnd-ms-plugin-config.pick">pick[]</link>
configuration directive found in mysqlnd_ms versions prior to
1.1.0-beta.
</para>
<para>
And the <literal>user</literal> filter replaces the
<function>mysqlnd_ms_set_user_pick_server</function> function, which was
previously used for this purpose.
</para>
</note>
<para>
The <literal>random</literal> filter implements the 'random' and 'random once'
load balancing policies. The 'round robin' load balancing can be configured
through the <literal>roundrobin</literal> filter. Setting a 'user defined
callback' for server selection is possible with the <literal>user</literal>
filter.
filter. The <literal>qos</literal> (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.
</para>
<para>
Filters can accept parameters to change their behaviour.
@ -842,15 +829,15 @@ version = 5.6.2-m5-log
</para>
<para>
One of the biggest strength of the filter concept is the possibility to
chain filters. This strength does not become immediately visible with the
filters provided by version 1.1.0-beta because all of the above filters
are supposed to output no more than one server. If a filter reduces
the list of candidates for running a statement to only one server, it
makes little sense to use that one server as input for another filter for
further reduction of the list of candidates.
chain filters. This strength does not become immediately visible because
tje <literal>random</literal>, <literal>roundrobin</literal> and
<literal>user</literal> filters are supposed to output no more than one server.
If a filter reduces the list of candidates for running a statement to
only one server, it makes little sense to use that one server as
input for another filter for further reduction of the list of candidates.
</para>
<para>
A filter sequence that will fail:
An example filter sequence that will fail:
<itemizedlist>
<listitem>
<simpara>
@ -891,11 +878,68 @@ version = 5.6.2-m5-log
line %d</literal>. Furthermore, an appropriate error on the connection handle
may be set.
</para>
<note>
<para>
A second type of filter exists: multi filter. A multi filter emits zero, one or multiple
servers after processing. The <literal>qos</literal> (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
to further reduce the list of candidates for statement execution until a candidate
is found.
</para>
<para>
A filter sequence with the <literal>qos</literal> (quality-of-service)
multi filter followed by a load balancing filter.
<itemizedlist>
<listitem>
<simpara>
Statement to be executed: <literal>SELECT sum(price) FROM orders WHERE order_id = 1</literal>.
Passed to all filters.
</simpara>
</listitem>
<listitem>
<simpara>
All configured nodes are passed as input to the first filter.
Master nodes: <literal>master_0</literal>.
Slave nodes: <literal>slave_0</literal>, <literal>slave_1</literal>,
<literal>slave_2</literal>, <literal>slave_3</literal>
</simpara>
</listitem>
<listitem>
<simpara>
Filter: <literal>qos</literal>, rule set: read-your-writes
Output: <literal>master_0</literal>
</simpara>
</listitem>
<listitem>
<simpara>
Output of <literal>master_0</literal>
and the statement to be executed
is passed as input to the next filter, which is <literal>roundrobin</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Filter: <literal>roundrobin</literal>. Server list consists of
one server. Round robin selects <literal>master_0</literal>.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
A filter sequence must not end with a multi filter. If trying to use
a filter sequence which ends with a multi filter the plugin may emit a
warning like <literal>(mysqlnd_ms) Error in configuration. Last filter is multi
filter. Needs to be non-multi one. Stopping in %s on line %d</literal>.
Furthermore, an appropriate error on the connection handle
may be set.
</para>
<para>
<note>
<title>Speculation towards the future: MySQL replication filtering</title>
<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>
In future versions, there may be additional multi filters.
For example, there may be a <literal>table</literal>
filter to support MySQL replication filtering. This would allow
you to define rules for which database or table is to be replicated to which
node of a replication cluster. Assume your replication cluster
@ -910,53 +954,6 @@ version = 5.6.2-m5-log
a load balancing filter to identify a server for statement execution.
</para>
</note>
<para>
A hypothetical filter sequence, assuming the existence of a <literal>table</literal>
filter to support MySQL replication filtering (client-side partitioning).
<itemizedlist>
<listitem>
<simpara>
Statement to be executed: <literal>SELECT col FROM sales.reports</literal>. Passed to all filters.
</simpara>
</listitem>
<listitem>
<simpara>
All configured nodes are passed as input to the first filter.
Master nodes: <literal>master_0</literal>.
Slave nodes: <literal>slave_0</literal>, <literal>slave_1</literal>,
<literal>slave_2</literal>, <literal>slave_3</literal>
</simpara>
</listitem>
<listitem>
<simpara>
Filter: <literal>table</literal>, rules set for database <literal>sales</literal>.
Output: <literal>slave_0</literal>, <literal>slave_1</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Output of <literal>slave_0</literal>, <literal>slave_1</literal>
and the statement to be executed
is passed as input to the next filter, which is <literal>roundrobin</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Filter: <literal>roundrobin</literal>. Server list consists of
two servers. Round robin selects <literal>slave_0</literal>.
Upon subsequent execution, if the same server list is given as
input, the filter will return <literal>slave_1</literal> followed
by <literal>slave_0</literal>, <literal>slave_1</literal>,
<literal>slave_0</literal> and so forth.
</simpara>
</listitem>
</itemizedlist>
<note>
<para>
The example aims to illustrate the strength of the filter
concept. It does not make any promises on future features.
</para>
</note>
</para>
</section>

107
reference/mysqlnd_ms/setup.xml
View file

@ -1117,6 +1117,107 @@ User has connected to 'myapp'...
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.filter_qos">
<term>
Filter: <parameter>qos</parameter>
<type>object</type>
</term>
<listitem>
<para>
The quality-of-service (qos) filter 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.
</para>
<para>
The <literal>qos</literal> 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
replication slave offers eventual consistency. The slave may not
be able to deliver requested data because it has not replicated the write,
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 <literal>qos</literal> can filter out cluster nodes
which cannot deliver the necessary quality of service.
</para>
<para>
The <literal>qos</literal> filter can be replaced
at runtime. A successful call to
<link linkend="function.mysqlnd-ms-set-qos"><function>mysqlnd_ms_set_qos</function></link>
removes all existing <literal>qos</literal> filter entries from the
filter list and installs a new one at the very beginning.
</para>
<informaltable>
<tgroup cols="3">
<colspec colwidth="10%"/>
<colspec colwidth="70%"/>
<colspec colwidth="20%"/>
<thead>
<row>
<entry>Keyword</entry>
<entry>Description</entry>
<entry>Version</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>eventual_consistency</literal>
</entry>
<entry>
<para>
Request eventual consistency. Allows the use of all
master and slave servers. Data returned may or may not be current.
</para>
</entry>
<entry>Since 1.2.0.</entry>
</row>
<row>
<entry>
<literal>session_consistency</literal>
</entry>
<entry>
<para>
Request session consistency (read your writes). Allows use of all masters
and all slaves which are in sync with the master.
If no further parameters are given slaves are filtered out
as there is no reliable way to test if a slave has caugth up
to the master or is lagging behind. Please note, if a filter chain
generates an empty slave list and the PHP configuration directive
<literal>mysqlnd_ms.multi_master=0</literal> is used, the plugin may
emit a warning.
</para>
<para>
Session consistency temporarily requested using
<function>mysqlnd_ms_set_qos</function> is a valuable alternative
to using <literal>master_on_write</literal>.
<literal>master_on_write</literal> is likely to send more statements
to the master than needed. The application may be able to contiue
operation at a lower consistency level after it has done
some critial reads.
</para>
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>strong_consistency</literal>
</entry>
<entry>
<para>
Request strong consistency. Only masters will be used.
</para>
</entry>
<entry>Since 1.2.0.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.failover">
<term>
<parameter>failover</parameter>
@ -1274,6 +1375,12 @@ User has connected to 'myapp'...
</programlisting>
</example>
</para>
<para>
Please, note the <literal>qos</literal> (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
<link linkend="mysqlnd-ms.qos_consistency">service levels</link>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.trx_stickiness">