README
1NAME
2 AnyEvent::Redis - Non-blocking Redis client
3
4SYNOPSIS
5 use AnyEvent::Redis;
6
7 my $redis = AnyEvent::Redis->new(
8 host => '127.0.0.1',
9 port => 6379,
10 encoding => 'utf8',
11 on_error => sub { warn @_ },
12 on_cleanup => sub { warn "Connection closed: @_" },
13 );
14
15 # callback based
16 $redis->set( 'foo'=> 'bar', sub { warn "SET!" } );
17 $redis->get( 'foo', sub { my $value = shift } );
18
19 my ($key, $value) = ('list_key', 123);
20 $redis->lpush( $key, $value );
21 $redis->lpop( $key, sub { my $value = shift });
22
23 # condvar based
24 my $cv = $redis->lpop( $key );
25 $cv->cb(sub { my $value = $_[0]->recv });
26
27DESCRIPTION
28 AnyEvent::Redis is a non-blocking (event-driven) Redis client.
29
30 This module is an AnyEvent user; you must install and use a supported
31 event loop.
32
33ESTABLISHING A CONNECTION
34 To create a new connection, use the new() method with the following
35 attributes:
36
37 host => <HOSTNAME>
38 Required. The hostname or literal address of the server.
39
40 port => <PORT>
41 Optional. The server port.
42
43 encoding => <ENCODING>
44 Optional. Encode and decode data (when storing and retrieving,
45 respectively) according to *ENCODING* ("utf8" is recommended or see
46 Encode::Supported for details on possible *ENCODING* values).
47
48 Omit if you intend to handle raw binary data with this connection.
49
50 on_error => $cb->($errmsg)
51 Optional. Callback that will be fired if a connection or
52 database-level error occurs. The error message will be passed to the
53 callback as the sole argument.
54
55 on_cleanup => $cb->($errmsg)
56 Optional. Callback that will be fired if a connection error occurs.
57 The error message will be passed to the callback as the sole
58 argument. After this callback, errors will be reported for all
59 outstanding requests.
60
61METHODS
62 All methods supported by your version of Redis should be supported.
63
64 Normal commands
65 There are two alternative approaches for handling results from commands:
66
67 * AnyEvent::CondVar based:
68
69 my $cv = $redis->command(
70 # arguments to command
71 );
72
73 # Then...
74 my $res;
75 eval {
76 # Could die()
77 $res = $cv->recv;
78 };
79 warn $@ if $@;
80
81 # or...
82 $cv->cb(sub {
83 my ($cv) = @_;
84 my ($result, $err) = $cv->recv
85 });
86
87 * Callback:
88
89 $redis->command(
90 # arguments,
91 sub {
92 my ($result, $err) = @_;
93 });
94
95 (Callback is a wrapper around the $cv approach.)
96
97 Transactions (MULTI/EXEC)
98 Redis transactions begin with a "multi" command and end with an "exec"
99 command. Commands in between are not executed immediately when they're
100 sent. On receipt of the "exec", the server executes all the saved
101 commands atomically, and returns all their results as one bulk reply.
102
103 After a transaction is finished, results for each individual command are
104 reported in the usual way. Thus, by the time any of these callbacks is
105 called, the entire transaction is finished for better or worse.
106
107 Results of the "exec" (containing all the other results) will be
108 returned as an array reference containing all of the individual results.
109 This may in some cases make callbacks on the individual commands
110 unnecessary, or vice versa. In this bulk reply, errors reported for each
111 individual command are represented by objects of class
112 "AnyEvent::Redis::Error", which will respond to a "->message" method
113 call with that error message.
114
115 It is not permitted to nest transactions. This module does not permit
116 subscription-related commands in a transaction.
117
118 Subscriptions
119 The subscription methods ("subscribe" and "psubscribe") must be used
120 with a callback:
121
122 my $cv = $redis->subscribe("test", sub {
123 my ($message, $channel[, $actual_channel]) = @_;
124 # ($actual_channel is provided for pattern subscriptions.)
125 });
126
127 The $cv condition will be met on unsubscribing from the channel.
128
129 Due to limitations of the Redis protocol the only valid commands on a
130 connection with an active subscription are subscribe and unsubscribe
131 commands.
132
133 Common methods
134 * get
135
136 * set
137
138 * hset
139
140 * hget
141
142 * lpush
143
144 * lpop
145
146 The Redis command reference (<http://redis.io/commands>) lists all
147 commands Redis supports.
148
149REQUIREMENTS
150 This requires Redis >= 1.2.
151
152COPYRIGHT
153 Tatsuhiko Miyagawa <miyagawa@bulknews.net> 2009-
154
155LICENSE
156 This library is free software; you can redistribute it and/or modify it
157 under the same terms as Perl itself.
158
159AUTHORS
160 Tatsuhiko Miyagawa
161
162 David Leadbeater
163
164 Chia-liang Kao
165
166 franck cuny
167
168 Lee Aylward
169
170 Joshua Barratt
171
172 Jeremy Zawodny
173
174 Leon Brocard
175
176 Michael S. Fischer
177
178 Chip Salzenberg
179
180SEE ALSO
181 Redis, AnyEvent
182
183