Mojo::Redis2 - Pure-Perl non-blocking I/O Redis driver
0.01
THIS MODULE IS UNDER DEVELOPMENT! FEEDBACK WANTED!
Mojo::Redis2 is a pure-Perl non-blocking I/O Redis driver for the Mojolicious real-time framework.
Redis is an open source, BSD licensed, advanced key-value cache and store. It is often referred to as a data structure server since keys can contain strings, hashes, lists, sets, sorted sets, bitmaps and hyperloglogs. - http://redis.io.
Features:
Blocking support
Mojo::Redis2 support blocking methods. NOTE: Calling non-blocking and blocking methods are supported on the same object, but might create a new connection to the server.
Error handling that makes sense
Mojo::Redis was unable to report back errors that was bound to an operation. Mojo::Redis2 on the other hand always make sure each callback receive an error message on error.
One object for different operations
Mojo::Redis had only one connection, so it could not do more than on blocking operation on the server side at the time (such as BLPOP, SUBSCRIBE, ...). This object creates new connections pr. blocking operation which makes it easier to avoid "blocking" bugs.
use Mojo::Redis2; my $redis = Mojo::Redis2->new; # Will die() on error. $res = $redis->set(foo => "42"); # $res = OK $res = $redis->get("foo"); # $res = 42
Mojo::IOLoop->delay( sub { my ($delay) = @_; $redis->ping($delay->begin)->get("foo", $delay->begin); }, sub { my ($delay, $ping_err, $ping, $get_err, $get) = @_; # On error: $ping_err and $get_err is set to a string # On success: $ping = "PONG", $get = "42"; }, );
Mojo::Redis2 can "subscribe" and re-use the same object to publish or run other Redis commands, since it can keep track of multiple connections to the same Redis server. It will also re-use the same connection when you (p)subscribe multiple times.
publish
$self->on(message => sub { my ($self, $message, $channel) = @_; }); $self->subscribe("some:channel" => sub { my ($self, $err) = @_; return $self->publish("myapp:errors" => $err) if $err; return $self->incr("subscribed:to:some:channel"); });
use Mojolicious::Lite; helper redis => sub { shift->stash->{redis} ||= Mojo::Redis2->new; }; get '/' => sub { my $c = shift; $c->delay( sub { my ($delay) = @_; $c->redis->get('some:message', $delay->begin); }, sub { my ($delay, $err, $message) = @_; $c->render(json => { error => $err, message => $message }); }, ); }; app->start;
$err in this document is a string containing an error message or empty string on success.
$err
$self->on(error => sub { my ($self, $err) = @_; ... });
Emitted if an error occurs that can't be associated with an operation.
$self->on(message => sub { my ($self, $message, $channel) = @_; });
Emitted when a $message is received on a $channel after it has been subscribed to.
$message
$channel
$self->on(pmessage => sub { my ($self, $message, $channel, $pattern) = @_; });
Emitted when a $message is received on a $channel matching a $pattern, after it has been subscribed to.
$pattern
$str = $self->encoding; $self = $self->encoding('UTF-8');
Holds the encoding using for data from/to Redis. Default is UTF-8.
$obj = $self->protocol; $self = $self->protocol($obj);
Holds an object used to parse/generate Redis messages. Defaults to Protocol::Redis::XS or Protocol::Redis.
Protocol::Redis::XS need to be installed manually.
$url = $self->url;
Holds a Mojo::URL object with the location to the Redis server. Default is MOJO_REDIS_URL or "redis://localhost:6379". The "url" need to be set in constructor. Examples:
MOJO_REDIS_URL
Mojo::Redis2->new(url => "redis://x:$auth_key\@$server:$port/$database_index"); Mojo::Redis2->new(url => "redis://10.0.0.42:6379"); Mojo::Redis2->new(url => "redis://10.0.0.42:6379/1"); Mojo::Redis2->new(url => "redis://x:s3cret\@10.0.0.42:6379/1");
In addition to the methods listed in this module, you can call these Redis methods on $self:
$self
append, echo, decr, decrby, del, exists, expire, expireat, get, getbit, getrange, getset, hdel, hexists, hget, hgetall, hincrby, hkeys, hlen, hmget, hmset, hset, hsetnx, hvals, incr, incrby, keys, lindex, linsert, llen, lpop, lpush, lpushx, lrange, lrem, lset, ltrim, mget, move, mset, msetnx, persist, ping, publish, randomkey, rename, renamenx, rpop, rpoplpush, rpush, rpushx, sadd, scard, sdiff, sdiffstore, set, setbit, setex, setnx, setrange, sinter, sinterstore, sismember, smembers, smove, sort, spop, srandmember, srem, strlen, sunion, sunionstore, ttl, type, zadd, zcard, zcount, zincrby, zinterstore, zrange, zrangebyscore, zrank, zrem, zremrangebyrank, zremrangebyscore, zrevrange, zrevrangebyscore, zrevrank, zscore and zunionstore.
See http://redis.io/commands for details.
$self = Mojo::Redis2->new(...);
Object constructor. Makes sure "url" is an object.
$self = $self->psubscribe(@patterns, sub { my ($self, $err, $res) = @_; ... });
Used to subscribe to channels that match @patterns. Messages arriving over a matching channel name will result in "pmessage" events.
@patterns
See http://redis.io/topics/pubsub for details.
$self = $self->subscribe(@channels, sub { my ($self, $err, $res) = @_; ... });
Used to subscribe to @channels. Messages arriving over a channel will result in "message" events.
@channels
$config = $class->start_server(\%config);
This method will try to start an instance of the Redis server or die() trying. "start_server" is a hack meant to be used in unit tests. (Any improvements are welcome)
die()
The returned $config is a hash-ref with these values, unless specified in the input %config.
$config
%config
bind: "localhost"
port: A randomly picked port
The "url" in MOJO_REDIS_URL environment variable is also set unless defined up front.
Copyright (C) 2014, Jan Henning Thorsen
This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
To install Mojo::Redis2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojo::Redis2
CPAN shell
perl -MCPAN -e shell install Mojo::Redis2
For more information on module installation, please visit the detailed CPAN module installation guide.