/ 
AnyEvent-Redis-0.1
River stage one • 5 direct dependents • 5 total dependents
/ AnyEvent::Redis::Subscriber

NAME

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

SYNOPSIS

use AnyEvent::Redis::Subscriber;
my $subscriber = AnyEvent::Redis::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::Redis::Subscriber is an event-driven (asynchronous) subscriber for the Redis publish/subscribe system.

The main idea is that other clients (such as AnyEvent::Redis) 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::Redis::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::Redis::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 ($subscriber, $channel, $message) = @_;
    print "Received message $message on channel $channel";
});

Dealing with errors

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

$subscriber->reg_cb(error => sub {
   my ($subscriber, $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 is not supported. Even though the wire protocol technically supports it, trust me, it's better this way :-).

SEE ALSO

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.