view release on metacpan or  search on metacpan

lib/Async/Redis.pm  view on Meta::CPAN

B<Important:> If you're embedding Async::Redis in a larger application
(web framework, existing event loop, etc.), see L</EVENT LOOP CONFIGURATION>
for how to properly configure Future::IO. Libraries should never configure
the Future::IO backend - only your application's entry point should.

=head1 DESCRIPTION

Async::Redis is an asynchronous Redis client built on L<Future::IO>,
providing a modern, non-blocking interface for Redis operations.

Key features:

=over 4

=item * Full async/await support via L<Future::AsyncAwait>

=item * Event loop agnostic (IO::Async, AnyEvent, UV, etc.)

=item * Automatic reconnection with exponential backoff

=item * Connection pooling with health checks

=item * Pipelining and auto-pipelining

=item * PubSub with automatic subscription replay on reconnect

When a connection drops during pub/sub mode and C<reconnect> is enabled,
all subscriptions are automatically re-established. Use
C<< $subscription->on_reconnect(sub { ... }) >> to be notified when this
happens (e.g., to re-poll state that may have changed during the outage).

=item * Transaction support (MULTI/EXEC/WATCH)

=item * TLS/SSL connections

=item * OpenTelemetry observability integration

=item * Fork-safe for pre-fork servers (Starman, etc.)

=item * Full RESP2 protocol support

=item * Safe concurrent commands on single connection

=back

=head1 CONCURRENT COMMANDS

Async::Redis safely handles multiple concurrent commands on a single
connection using a response queue pattern. When you fire multiple async
commands without explicitly awaiting them:

    my @futures = (
        $redis->set('k1', 'v1'),
        $redis->set('k2', 'v2'),
        $redis->get('k1'),
    );
    my @results = await Future->needs_all(@futures);

Each command is registered in an inflight queue before being sent to Redis.
A single reader coroutine processes responses in FIFO order, matching each
response to the correct waiting future. This prevents response mismatch bugs
that can occur when multiple coroutines race to read from the socket.

For high-throughput scenarios, consider using:

=over 4

=item * B<Explicit pipelines> - C<< $redis->pipeline >> batches commands
for a single network round-trip

=item * B<Auto-pipeline> - C<< auto_pipeline => 1 >> automatically batches
commands within an event loop tick

=item * B<Connection pools> - L<Async::Redis::Pool> for parallel execution
across multiple connections

=back

=head1 CONSTRUCTOR

=head2 new

    my $redis = Async::Redis->new(%options);

Creates a new Redis client instance. Does not connect immediately.

Options:

=over 4

=item host => $hostname

Redis server hostname. Default: 'localhost'

=item port => $port

Redis server port. Default: 6379

=item uri => $uri

Connection URI (e.g., 'redis://user:pass@host:port/db').
If provided, overrides host, port, password, database options.

=item path => $path

Unix domain socket path. When provided, C<host> and C<port> are ignored.
Also available via C<redis+unix://> URIs.

=item password => $password

Authentication password.

=item username => $username

Authentication username (Redis 6+ ACL).

=item database => $db

Database number to SELECT after connect. Default: 0

=item tls => $bool | \%options