Browse Source

[doc] clustering - incorporating draft feedback

Distribution strategy section expanded and moved under
`PredisCluster` connection class documentation. Connection classes now
have section titles. Spelling an accuracy fixes from PR feedback.
Dominic Scheirlinck 12 years ago
parent
commit
87cb0c1eca
1 changed files with 76 additions and 39 deletions
  1. 76 39
      doc/clustering.rst

+ 76 - 39
doc/clustering.rst

@@ -1,5 +1,4 @@
 .. vim: set ts=3 sw=3 et :
 .. vim: set ts=3 sw=3 et :
-
 .. php:namespace:: Predis
 .. php:namespace:: Predis
 
 
 Clustering
 Clustering
@@ -18,24 +17,6 @@ cluster, your available space increases. At the same time, commands should be
 distributed between the nodes, meaning each individual node has to service
 distributed between the nodes, meaning each individual node has to service
 less requests.
 less requests.
 
 
-
-Distribution Strategy
-=====================
-
-Exactly how keys are split across a cluster is specified by a
-:term:`distribution strategy`. There are two distribution strategy classes shipped
-with Predis. What they have in common is that they try to manage the task of
-adding and removing servers from the cluster cleverly.
-
-When a server is added or removed, the distribution strategy takes care of
-ensuring that as few keys as possible have to be moved between the remaining
-servers. When you remove a server from a clustered connection of ten servers,
-ideally you'd only like 10% of your keys to be newly missing.
-
-This is broadly known as "`consistent hashing`_".
-
-.. _consistent hashing: https://en.wikipedia.org/wiki/Consistent_hashing
-
 Configuring a Cluster
 Configuring a Cluster
 =====================
 =====================
 
 
@@ -72,8 +53,8 @@ all in an array::
 You can still use the URI syntax to configure the connections::
 You can still use the URI syntax to configure the connections::
 
 
    $client = new Predis\Client(array(
    $client = new Predis\Client(array(
-       'tcp://127.0.0.1:6370?alias=first&db=0',
-       'tcp://127.0.0.1:6370?alias=second&db=1'
+       'tcp://127.0.0.1:6370?alias=first&database=0',
+       'tcp://127.0.0.1:6370?alias=second&database=1'
    ), $options);
    ), $options);
 
 
 .. note::
 .. note::
@@ -91,7 +72,7 @@ The ``cluster`` Client Option
 '''''''''''''''''''''''''''''
 '''''''''''''''''''''''''''''
 .. php:namespace:: Predis\Connection
 .. php:namespace:: Predis\Connection
 
 
-You can optionally confiugre your client's clustering by using the ``cluster``
+You can optionally configure your client's clustering by using the ``cluster``
 client option. This option can take a few different types of value. It can take
 client option. This option can take a few different types of value. It can take
 the special strings ``"predis"`` or ``"redis"`` to switch between the two
 the special strings ``"predis"`` or ``"redis"`` to switch between the two
 built-in cluster connection classes `PredisCluster` and
 built-in cluster connection classes `PredisCluster` and
@@ -105,37 +86,93 @@ If the value is any other string, it's expected to be the fully qualified name
 of a class implementing `ClusterConnectionInterface`.
 of a class implementing `ClusterConnectionInterface`.
 
 
 Finally, you can also configure the option with a callable. This callable is
 Finally, you can also configure the option with a callable. This callable is
-expected to return an instance of `ClusterConnectionInterface`. The two
-built-in clustered connection types both accept a
-`Predis\\Cluster\\Distribution\\DistributionStrategyInterface` instance as
-their first argument, allowing you to configure that as well::
+expected to return an instance of `ClusterConnectionInterface`::
 
 
    $client = new Predis\Client(array(
    $client = new Predis\Client(array(
        // ...
        // ...
    ), array(
    ), array(
       'cluster' => function () {
       'cluster' => function () {
-         $strategy = new Predis\Cluster\Distribution\KetamaPureRing();
-         return new Predis\Connection\PredisCluster($strategy);
+         return new Predis\Connection\PredisCluster();
       }
       }
    ));
    ));
 
 
-Connection Classes
-""""""""""""""""""
+
+Provided Connection Classes
+===========================
+
+PredisCluster
+'''''''''''''
 
 
 .. php:class:: PredisCluster
 .. php:class:: PredisCluster
 
 
-  ``PredisCluster`` is a simple Predis-native clustered connection implementation.
+   ``PredisCluster`` is a simple Predis-native clustered connection implementation.
+
+This form of clustered connection does *not* provide redundancy. If your
+application makes requests for 100 different keys, with the default
+distribution strategy these keys are likely to be spit across all the servers
+in your pool.
 
 
-  This form of clustered connection does *not* provide redundancy. If your application
-  makes requests for 100 different keys, with the default distribution strategy
-  these keys are likely to be spit across all the servers in your pool.
+Distribution Strategy
+:::::::::::::::::::::
+
+Exactly how keys are split across a cluster is specified by a
+:term:`distribution strategy`. There are two distribution strategy classes
+shipped with Predis. What they have in common is that they try to manage the
+task of adding and removing servers from the cluster cleverly. When a server is
+added or removed, the distribution strategy takes care of ensuring that as few
+keys as possible have to be moved between the remaining servers. When you
+remove a server from a clustered connection of ten servers, ideally you'd only
+like 10% of your keys to be newly missing.
+
+This is broadly known as "`consistent hashing`_".
+
+It's also worth noting what a distribution strategy doesn't do: it doesn't
+actually ensure availability of your data between different cluster
+configurations. Or, more accurately, it leaves this up to you.
+
+You might decide to take the naive approach: that if a node goes offline, it'll take a
+portion of your keyspace with it. This might not matter to your application,
+especially if you can recalculate the data you were storing, or if you're using
+your cluster as a cache.
+
+If this sort of availability does matter for your application, it's up to you
+to take care of it, using tools external to Predis. You may want to move data
+before taking a node offline, for instance, ensuring minimal disruption. The
+fact that you can customize or replace the distribution strategy should make
+integrating such tools with `PredisCluster` much easier. For example, you may
+want to use a `Predis\\Cluster\\Distribution\\KetamaPureRing` strategy,
+combined with `libketama`_-based tools.
+
+The distribution strategy for a `PredisCluster` must implement
+`Predis\\Cluster\\Distribution\\DistributionStrategyInterface`. You pass your
+strategy into the `PredisCluster` instance as the first argument, using a
+'cluster' client-option callback::
+
+   $client = new Predis\Client(array(
+       // ...
+   ), array(
+      'cluster' => function () {
+         $strategy = new Predis\Cluster\Distribution\KetamaPureRing();
+         return new Predis\Connection\PredisCluster($strategy);
+      }
+   ));
+
+.. _consistent hashing: https://en.wikipedia.org/wiki/Consistent_hashing
+.. _libketama:          https://github.com/RJ/ketama
+
+RedisCluster
+''''''''''''
 
 
 .. php:class:: RedisCluster
 .. php:class:: RedisCluster
 
 
-  ``RedisCluster`` is a clustered connection implementation intended for use with
-  Redis Cluster. Redis Cluster is not yet finalized, but it already includes some
-  pretty cool features. Nodes in a Redis Cluster arrangement configure
-  themselves to deal with changes in availability.
+   ``RedisCluster`` is a clustered connection implementation intended for use with
+   Redis Cluster.
+
+Redis Cluster is not yet finalized, but it already includes some
+pretty cool features. Nodes in a Redis Cluster arrangement configure
+themselves to deal with changes in availability. Once consequence of this is
+that a distribution strategy is unnecessary: nodes in this cluster type agree
+and decide themselves about which node is to serve a portion of the keyspace.
 
 
 Disallowed Commands
 Disallowed Commands
 ===================
 ===================
@@ -145,7 +182,7 @@ example, the ``INFO`` command returns information about the server on which
 it's run, so running it on a cluster would be meaningless.
 it's run, so running it on a cluster would be meaningless.
 
 
 If you try to run one of these commands, you'll get a
 If you try to run one of these commands, you'll get a
-``Predis\\NotSupportedException``.
+`Predis\\NotSupportedException`.
 
 
 Running Commands on Nodes
 Running Commands on Nodes
 =========================
 =========================