view release on metacpan or  search on metacpan

lib/AnyEvent/Redis/Federated.pm  view on Meta::CPAN

still down, backing off" to let you know that the back-off logic is
about to kick in.  Each time the retry_interval is increased, it will
C<warn()> "redis server $server retry_interval now $retry_interval".

If a down server does come back up, the module will C<warn()> "redis
server $server back up (down since $down_since)\n" where $down_since
is human readable timestamp.  It will also clear all internal state
about the down server.

=head2 TIMEOUTS

This module provides support for command timeouts.

The command timeout controls how long we're willing to wait for a
response to a given request made to a Redis server.  Redis usually
responds VERY quickly to most requests.  But if there's a temporary
network problem or something tying up the server, you may wish to fail
quickly and move on.

NOTE: these timeouts are implemented using C<alarm()>, so be careful
of also using C<alarm()> calls in your own code that could interfere.

=head2 MULTI-KEY OPERATIONS

Some operations can operate on many keys and might cross server
boundries.  They are currently supported provided that you remember to
specify a hash key to ensure the all live on the same node.  Example
operations are:

  * mget
  * sinter
  * sinterstore
  * sdiff
  * sdiffstore
  * zunionstore

Previous versions of this module listed these as unsupported commands,
but that's rather limiting.  So they're supported now, provided you
know what you're doing.

=head2 METHODS

AnyEvent::Redis::Federated inherits all of the normal Redis methods.
However, you can supply a callback or AnyEvent condvar as the final
argument and it'll do the right thing:

  $redis->get("foo", sub { print shift,"\n"; });

You can also use call chaining:

  $redis->set("foo", 1)->set("bar", 2)->get("foo", sub {
    my $val = shift;
    print "foo: $val\n";
  });

=head2 CONFIGURATION

AnyEvent::Redis::Federated requires a configuration hash be passed
to it at instantiation time. The constructor will die() unless a
unless a 'config' option is passed to it. The configuration structure
looks like:

  my $config = {
    nodes => {
      redis_1 => { address => 'db1:63790' },
      redis_2 => { address => 'db1:63791' },
      redis_3 => { address => 'db2:63790' },
      redis_4 => { address => 'db2:63791' },
    },
  };

The "nodes" and "master_of" hashes are described below.

=head3 NODES

The "nodes" configuation maps an arbitrary node name to a host:port
pair.  (The hostname can be replaced with an IP address.)

Node names (redis_N in the example above) are VERY important since
they are the keys used to build the consistent hashing ring. It's
generally the wrong idea to change a node name. Since node names are
mapped to a host:port pair, we can move a node from one host to
another without rehashing a bunch of keys.

There is unlikely to be a need to remove a node.

Adding nodes to a cluster is currently not well-supported, but is an
area of active development.

=head2 EVENT LOOP

Since this module wraps AnyEvent::Redis, there are two main ways you
can integrate it into your code.  First, if you're using AnyEvent, it
should "just work."  However, if you're not otherwise using AnyEvent,
you can still take advantage of batching up requests and waiting for
them in parallel by calling the C<poll()> method as illustrated in the
synopsis.

Calling C<poll()> asks the module to issue any pending requests and
wait for all of them to return before returning control back to your
code.

=head2 EXPORT

None.

=head2 SEE ALSO

The normal AnyEvent::Redis perl client C<perldoc AnyEvent::Redis>.

The Redis API documentation:

  http://redis.io/commands

Jeremy Zawodny's blog describing craigslist's use of redis sharding:

  http://blog.zawodny.com/2011/02/26/redis-sharding-at-craigslist/

That posting described an implementation which was based on the
regular (non-async) Redis client from CPAN.  This code is a port of
that to AnyEvent.