The following documentation is automatically generated. Please do not edit this file, but rather the original, inline with Net::Async::Redis at lib/Net/Async/Redis.pm (on the system that originally ran this). If you do edit this file, and don't want your changes to be removed, make sure you change the first line.
Net::Async::Redis - talk to Redis servers via IO::Async
use Net::Async::Redis; use Future::AsyncAwait; use IO::Async::Loop; my $loop = IO::Async::Loop->new; $loop->add(my $redis = Net::Async::Redis->new); (async sub { await $redis->connect; my $value = await $redis->get('some_key'); $value ||= await $redis->set(some_key => 'some_value'); print "Value: $value"; })->()->get; # You can also use ->then chaining, see L<Future> for more details $redis->connect->then(sub { $redis->get('some_key') })->then(sub { my $value = shift; return Future->done($value) if $value; $redis->set(some_key => 'some_value') })->on_done(sub { print "Value: " . shift; })->get; # ... or with Future::AsyncAwait await $redis->connect; my $value = await $redis->get('some_key'); $value ||= await $redis->set(some_key => 'some_value'); print "Value: $value";
Provides client access for dealing with Redis servers.
See Net::Async::Redis::Commands for the full list of commands, this list is autogenerated from the official documentation here:
https://redis.io/commands
This is intended to be a near-complete low-level client module for asynchronous Redis support. See Net::Async::Redis::Server for a (limited) Perl server implementation. It is an unofficial Perl port and not endorsed by the Redis server maintainers in any way.
Current features include:
all commands as of 5.0.8 (April 2020), see https://redis.io/commands for the methods and parameters
pub/sub support, see "Subscriptions"
pipelining, see "Pipelining"
transactions, see "Transactions"
streams and consumer groups, see "Streams"
As with any other IO::Async::Notifier-based module, you'll need to add this to an IO::Async::Loop:
my $loop = IO::Async::Loop->new; $loop->add( my $redis = Net::Async::Redis->new );
then connect to the server:
$redis->connect ->then(sub { # You could achieve a similar result by passing client_name in # constructor or ->connect parameters $redis->client_setname("example client") })->get;
One of the most common Redis scenarios is as a key/value store. The "get" and "set" methods are typically used here:
$redis->set(some_key => 'some value') ->then(sub { $redis->get('some_key') })->on_done(sub { my ($value) = @_; print "Read back value [$value]\n"; })->retain;
See the next section for more information on what these methods are actually returning.
Requests are implemented as methods on the Net::Async::Redis object. These typically return a Future which will resolve once ready:
my $future = $redis->incr("xyz") ->on_done(sub { print "result of increment was " . shift . "\n" });
For synchronous code, call ->get on that Future:
->get
print "Database has " . $redis->dbsize->get . " total keys\n";
This means you can end up with ->get being called on the result of ->get, note that these are two very different methods:
$redis ->get('some key') # this is being called on $redis, and is issuing a GET request ->get # this is called on the returned Future, and blocks until the value is ready
Typical async code would not be expected to use the "get" in Future method extensively; often only calling it in one place at the top level in the code.
Since Future is used for deferred results, failure is indicated by a failing Future with failure category of redis.
redis
The "catch" in Future feature may be useful for handling these:
$redis->lpush(key => $value) ->catch( redis => sub { warn "probably an incorrect type, cannot push value"; Future->done } )->get;
Note that this module uses Future::AsyncAwait internally.
NOTE: For a full list of the Redis methods supported by this module, please see Net::Async::Redis::Commands.
See https://redis.io/topics/pubsub for more details on this topic. There's also more details on the internal implementation in Redis here: https://making.pusher.com/redis-pubsub-under-the-hood/.
Subscribes to a pattern.
Example:
# Subscribe to 'info::*' channels, i.e. any message # that starts with the C<info::> prefix, and prints them # with a timestamp. $redis_connection->psubscribe('info::*') ->then(sub { my $sub = shift; $sub->map('payload') ->each(sub { print localtime . ' ' . $_ . "\n"; })->retain })->get; # this will block until the subscribe is confirmed. Note that you can't publish on # a connection that's handling subscriptions due to Redis protocol restrictions. $other_redis_connection->publish('info::example', 'a message here')->get;
Returns a Future which resolves to a Net::Async::Redis::Subscription instance.
Subscribes to one or more channels.
# Subscribe to 'notifications' channel, # print the first 5 messages, then unsubscribe $redis->subscribe('notifications') ->then(sub { my $sub = shift; $sub->events ->map('payload') ->take(5) ->say ->completed })->then(sub { $redis->unsubscribe('notifications') })->get
Executes the given code in a Redis MULTI transaction.
MULTI
This will cause each of the requests to be queued on the server, then applied in a single atomic transaction.
Note that the commands will resolve only after the transaction is committed: for example, when the "set" command is issued, Redis will return QUEUED. This information is not used as the result - we only pass through the immediate response if there was an error. The Future representing the response will be marked as done once the EXEC command is applied and we have the results back.
QUEUED
EXEC
$redis->multi(sub { my $tx = shift; $tx->incr('some::key')->on_done(sub { print "Final value for incremented key was " . shift . "\n"; }); $tx->set('other::key => 'test data') })->then(sub { my ($success, $failure) = @_; return Future->fail("Had $failure failures, expecting everything to succeed") if $failure; print "$success succeeded\m"; return Future->done; })->retain;
A convenience wrapper around the keyspace notifications API.
Provides the necessary setup to establish a PSUBSCRIBE subscription on the __keyspace@*__ namespace, setting the configuration required for this to start emitting events, and then calls $code with each event.
PSUBSCRIBE
__keyspace@*__
$code
Note that this will switch the connection into pubsub mode, so it will no longer be available for any other activity.
Resolves to a Ryu::Source instance.
The string describing the remote endpoint.
A string describing the local endpoint, usually host:port.
host:port
Connects to the Redis server.
Will use the "configure"d parameters if available, but as a convenience can be passed additional parameters which will then be applied as if you had called "configure" with those beforehand. This also means that they will be preserved for subsequent "connect" calls.
Establishes a connection if needed, otherwise returns an immediately-available Future instance.
Called for each incoming message.
Passes off the work to "handle_pubsub_message" or the next queue item, depending on whether we're dealing with subscriptions at the moment.
Represents the IO::Async::Stream instance for the active Redis connection.
Number of requests awaiting responses before we start queuing. This defaults to an arbitrary value of 100 requests.
Note that this does not apply when in transaction (MULTI) mode.
See https://redis.io/topics/pipelining for more details on this concept.
This are still supported, but no longer recommended.
Called when the socket is closed.
Generate a label for the given command list.
Defines the buffer size when reading from a Redis connection.
Defaults to 1MB, reduce this if you're dealing with a lot of connections and want to minimise memory usage. Alternatively, if you're reading large amounts of data and spend too much time in needless epoll_wait calls, try a larger value.
epoll_wait
The buffer size when writing to Redis connections, in bytes. Defaults to 1MB.
See "stream_read_len".
Some other Redis implementations on CPAN:
Mojo::Redis2 - nonblocking, using the Mojolicious framework, actively maintained
MojoX::Redis - changelog mentions that this was obsoleted by Mojo::Redis, although there have been new versions released since then
RedisDB - another synchronous (blocking) implementation, handles pub/sub and autoreconnect
Cache::Redis - wrapper around RedisDB
Redis::Fast - wraps hiredis, faster than Redis
hiredis
Redis::Jet - also XS-based, docs mention very early development stage but appears to support pipelining and can handle newer commands via ->command.
very early development stage
->command
Redis - synchronous (blocking) implementation, handles pub/sub and autoreconnect
Tom Molesworth <TEAM@cpan.org>
acl_cat, acl_deluser, acl_genpass, acl_list, acl_load, acl_log, acl_save, acl_setuser, acl_users, acl_whoami, append, auth, bgrewriteaof, bgsave, bitcount, bitfield, bitop, bitpos, blpop, brpop, brpoplpush, bzpopmax, bzpopmin, client_getname, client_id, client_kill, client_list, client_pause, client_reply, client_setname, client_unblock, cluster_addslots, cluster_bumpepoch, cluster_count_failure_reports, cluster_countkeysinslot, cluster_delslots, cluster_failover, cluster_flushslots, cluster_forget, cluster_getkeysinslot, cluster_info, cluster_keyslot, cluster_meet, cluster_myid, cluster_nodes, cluster_replicas, cluster_replicate, cluster_reset, cluster_saveconfig, cluster_set_config_epoch, cluster_setslot, cluster_slaves, cluster_slots, command, command_count, command_getkeys, command_info, config_get, config_resetstat, config_rewrite, config_set, dbsize, debug_object, debug_segfault, decr, decrby, del, dump, echo, eval, evalsha, exists, expire, expireat, flushall, flushdb, geoadd, geodist, geohash, geopos, georadius, georadiusbymember, get, getbit, getrange, getset, hdel, hexists, hget, hgetall, hincrby, hincrbyfloat, hkeys, hlen, hmget, hmset, hscan, hset, hsetnx, hstrlen, hvals, incr, incrby, incrbyfloat, info, lastsave, latency_doctor, latency_graph, latency_help, latency_history, latency_latest, latency_reset, lindex, linsert, llen, lolwut, lpop, lpush, lpushx, lrange, lrem, lset, ltrim, memory_doctor, memory_help, memory_malloc_stats, memory_purge, memory_stats, memory_usage, mget, migrate, module_list, module_load, module_unload, monitor, move, mset, msetnx, object, persist, pexpire, pexpireat, pfadd, pfcount, pfmerge, ping, psetex, psync, pttl, publish, pubsub, punsubscribe, quit, randomkey, readonly, readwrite, rename, renamenx, replicaof, restore, role, rpop, rpoplpush, rpush, rpushx, sadd, save, scan, scard, script_debug, script_exists, script_flush, script_kill, script_load, sdiff, sdiffstore, select, set, setbit, setex, setnx, setrange, shutdown, sinter, sinterstore, sismember, slaveof, slowlog, smembers, smove, sort, spop, srandmember, srem, sscan, strlen, sunion, sunionstore, swapdb, sync, time, touch, ttl, type, unlink, unsubscribe, unwatch, wait, watch, xack, xadd, xclaim, xdel, xgroup, xinfo, xlen, xpending, xrange, xread, xreadgroup, xrevrange, xtrim, zadd, zcard, zcount, zincrby, zinterstore, zlexcount, zpopmax, zpopmin, zrange, zrangebylex, zrangebyscore, zrank, zrem, zremrangebylex, zremrangebyrank, zremrangebyscore, zrevrange, zrevrangebylex, zrevrangebyscore, zrevrank, zscan, zscore, zunionstore
add_child, adopt_future, adopted_futures, can_event, children, configure_unknown, debug_printf, get_loop, invoke_error, invoke_event, loop, make_event_cb, maybe_invoke_event, maybe_make_event_cb, new, notifier_name, parent, remove_child, remove_from_parent
With thanks to the following for contributing patches, bug reports, tests and feedback:
BINARY@cpan.org
PEVANS@cpan.org
@eyadof
Copyright Tom Molesworth and others 2015-2020. Licensed under the same terms as Perl itself.
To install Net::Async::Redis, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Async::Redis
CPAN shell
perl -MCPAN -e shell install Net::Async::Redis
For more information on module installation, please visit the detailed CPAN module installation guide.