/ 
AnyEvent-Redis2-0.3
/ AnyEvent::Redis2

NAME

AnyEvent::Redis2 - an event-driven Redis client

SYNOPSIS

use AnyEvent::Redis2;
my $redis = AnyEvent::Redis2->connect(
    host => 'redis',
    on_connect => $cb, 
    on_connect_error => $errcb,
    on_error => $errcb,
);

# Generic query method
$redis->query('SET', $key, $value, $cb);

# Autoloaded query method
$redis->set($key, $value, $cb);

DESCRIPTION

This module is an AnyEvent user; you must use and run a supported event loop.

AnyEvent::Redis2 is an event-driven (asynchronous) client for the Redis key-value (NoSQL) database server. Every operation is supported, except subscription to Redis "classes" (i.e. channels), which is supported by AnyEvent::Redis::Subscriber. However, this module may be used to publish to channels.

Establishing a connection

To connect to the Redis server, use the connect() method:

my $redis = AnyEvent::Redis2->connect(host => <host>, ...);

The host argument is required.

Optional (but recommended) arguments include:

port => $port

Connect to the server on the specified port number. (If not specified, the default port will be used.)

auth => $password

Authenticate to the server with the given password.

on_connect => $cb->($host, $port)

Specifies a callback to be executed upon a successful connection. The actual peer host and port number will be passed as arguments to the callback.

on_connect_error => $cb->($errmsg)

Specifies a callback to be executed if the connection failed (or authentication failed). The error message will be passed to the callback.

The callback may return an interval value (as a fractional number); if specified, the client will automatically attempt to reconnect at that interval until successful.

on_error => $cb->($errmsg)

Specifies a callback to be executed if an I/O error occurs (e.g. connection reset by peer). The error message will be passed to the callback.

The callback may return an interval value (as a fractional number); if specified, the client will automatically attempt to reconnect at that interval until successful.

Queries and responses

After you have successfully connected to the server, you can issue queries to it. (You'll want to do this in the on_connect callback handler fired by connect(), above.)

To issue a query, use the query() method:

$cv = $redis->query(@args, [ $cb->($data, $error) ]);

The initial list of arguments to query() comprise the actual command. (See the command reference http://code.google.com/p/redis/wiki/CommandReference for a list of available commands.)

The final argument to query() specifies a optional callback (code reference) that will be fired when a response to the query is received. It will be called with the data (either a scalar, or an ARRAY reference for a multi-bulk response) as the first argument, and a scalar indicating whether the data is an error message as the second argument.

query() will return an AnyEvent condition variable that can also be used to retrieve the results via its recv() method (or via cb() if you don't want to block). If an error occurs, recv() will die, so be sure to wrap it in an eval:

my $cv = $redis->query(@args);
eval { 
    my $result = $cv->recv; 
    # ...
};
if ($@) {
    warn "server error: $@";
    ...
}

Alternatively, you may invoke Redis commands as methods, e.g.:

$cv = $redis->set(key1 => $val1, [ $cb->($result, $error) ]);
$cv = $redis->lrange('list', 0, 1000, [ $cb->($result, $error) ]);
$cv = $redis->get(key1, [ $cb->($result, $error) ]);

WHY NOT AnyEvent::Redis?

AnyEvent::Redis2 began as a from-scratch implementation of a Redis module for AnyEvent. (When I began writing it, I didn't know such a module already existed.) Instead of abandoning it when I realized my oversight, I decided to contribute it.

The substantive differences from AnyEvent::Redis are:

Better documentation
Automatic reconnection capability
on_connect() callback
Simpler, faster protocol parser (about 30% faster sending large numbers of queries; about 10% faster receiving bulk responses)
Easier-to-read code
Explicit separation of subscriber functionality (into AnyEvent::Redis2::Subscriber)

SEE ALSO

Redis Command Reference http://code.google.com/p/redis/wiki/CommandReference

AUTHOR

Michael S. Fischer <michael+cpan@dynamine.net>

COPYRIGHT AND LICENSE

Copyright (C) 2010 Michael S. Fischer.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.