/ 
AnyEvent-Redis2-0.3
/ AnyEvent::Redis2::Subscriber

NAME

AnyEvent::Redis2::Subscriber - event-driven Redis subscriber client

SYNOPSIS

use AnyEvent::Redis2::Subscriber;
my $subscriber = AnyEvent::Redis2::Subscriber->subscribe(
    host => 'redis', 
    channel => 'z'
);
$subscriber->reg_cb(message => sub {
    my ($subscriber, $message) = @_;
    # ...
};

DESCRIPTION

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

AnyEvent::Redis2::Subscriber is an event-driven (asynchronous) subscriber for the Redis publish/subscribe system.

The main idea is that other clients (such as AnyEvent::Redis2) publish messages to a specified channel (or class, in Redis-speak), which are then received by each client that has subscribed to the channel.

Unlike some other publish/subscribe mechanisms which are producer-consumer based, Redis' publish/subscribe mechanism is broadcast-based: every subscriber to a channel receives every message sent to that channel; and messages are not queued for future delivery if there are no subscribers for that channel.

Subscribing to a channel

To subscribe to a channel, call the subscribe() method:

my $subscriber = AnyEvent::Redis2::Subscriber->subscribe(
   host => $host,
   channel => $channel,
   ...
);

This immediately establishes a connection to the Redis server at the given host and subscribes to the specified channel.

Pattern-based subscriptions are also possible. Instead of specifying a channel, a pattern may be specified consisting of a glob pattern that matches channel names. For example, if chan_* is specified, then the client will receive every message sent to "chan_1", "chan_2", "chan_zebra", and so forth while connected to the server:

my $subscriber = AnyEvent::Redis2::Subscriber->subscribe(
   host => $host,
   pattern => $pattern,
   ...
);

Optional arguments include:

port => $port

Connect to the Redis server at $port. If undefined, the default port (6379) is used.

auth => $password

Authenticate to the server with the given password.

Receiving messages

To receive messages, register a callback for the message event. When a message is received, the callback will be fired with the message and the channel it was received on:

$subscriber->reg_cb(message => sub {
    my ($channel, $message) = @_;
    print "Received message $message on channel $channel";
});

If you've subscribed to a channel pattern, you may also register a callback for the pmessage event. When a message is received, the callback will be fired with the message, the channel it was received on, and the pattern:

$subscriber->reg_cb(pmessage => sub {
    my ($pattern, $channel, $message) = @_;
    print "Received message $message on channel $channel (pattern $pattern)";
});

Dealing with errors

To be notified of errors (which can occur at connect time or thereafter), register a callback with the error event as follows:

$subscriber->reg_cb(error => sub {
   my ($errmsg) = @_;
   # ...
});

WARNING: As with all AnyEvent modules, you must not die() in a callback!

Unsubscribing

To unsubscribe, just undef the subscriber handle. Reusing handles for subsequent subscriptions (i.e., changing the channel) is not supported. Even though the wire protocol technically supports it, trust me, it's better this way :-).

SEE ALSO

AnyEvent::Redis2, Redis PublishSubscribe http://code.google.com/p/redis/wiki/PublishSubscribe

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.