view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

[AnyEvent](https://metacpan.org/pod/AnyEvent) has a support for EV as its one of backends, so [EV::Redis](https://metacpan.org/pod/EV%3A%3ARedis) can be used in your AnyEvent applications seamlessly.

# NO UTF-8 SUPPORT

Unlike other redis modules, this module doesn't support utf-8 string.

This module handle all variables as bytes. You should encode your utf-8 string before passing commands like following:

    use Encode;
    
    # set $val
    $redis->set(foo => encode_utf8 $val, sub { ... });
    
    # get $val
    $redis->get(foo, sub {
        my $val = decode_utf8 $_[0];
    });

# METHODS

## new(%options);

Create new [EV::Redis](https://metacpan.org/pod/EV%3A%3ARedis) instance.

Available `%options` are:

- host => 'Str'
- port => 'Int'

    Hostname and port number of redis-server to connect. Mutually exclusive with `path`.

- path => 'Str'

    UNIX socket path to connect. Mutually exclusive with `host`.

- on\_error => $cb->($errstr)

    Error callback will be called when a connection level error occurs.
    If not provided (or `undef`), a default handler that calls `die` is
    installed. To have no error handler, call `$obj->on_error(undef)`
    after construction.

    This callback can be set by `$obj->on_error($cb)` method any time.

- on\_connect => $cb->()

    Connection callback will be called when connection successful and completed to redis server.

    This callback can be set by `$obj->on_connect($cb)` method any time.

- on\_disconnect => $cb->()

    Disconnect callback will be called when disconnection occurs (both normal and error cases).

    This callback can be set by `$obj->on_disconnect($cb)` method any time.

- on\_push => $cb->($reply)

    RESP3 push callback for server-initiated out-of-band messages (Redis 6.0+).
    Called with the decoded push message (an array reference). This enables
    client-side caching invalidation and other server-push features.

    This callback can be set by `$obj->on_push($cb)` method any time.

- connect\_timeout => $num\_of\_milliseconds

    Connection timeout.

- command\_timeout => $num\_of\_milliseconds

    Command timeout.

- max\_pending => $num

    Maximum number of commands sent to Redis concurrently. When this limit is reached,
    additional commands are queued locally and sent as responses arrive.
    0 means unlimited (default). Use `waiting_count` to check the local queue size.

- waiting\_timeout => $num\_of\_milliseconds

    Maximum time a command can wait in the local queue before being cancelled with
    "waiting timeout" error. 0 means unlimited (default).

- resume\_waiting\_on\_reconnect => $bool

    Controls behavior of waiting queue on disconnect. If false (default), waiting
    commands are cancelled with error on disconnect. If true, waiting commands are
    preserved and resumed after successful reconnection.

- reconnect => $bool

    Enable automatic reconnection on connection failure or unexpected disconnection.
    Default is disabled (0).

- reconnect\_delay => $num\_of\_milliseconds

    Delay between reconnection attempts. Default is 1000 (1 second).

- max\_reconnect\_attempts => $num

    Maximum number of reconnection attempts. 0 means unlimited. Default is 0.
    Negative values are treated as 0 (unlimited).

- priority => $num

    Priority for the underlying libev IO watchers. Higher priority watchers are
    invoked before lower priority ones. Valid range is -2 (lowest) to +2 (highest),
    with 0 being the default. See [EV](https://metacpan.org/pod/EV) documentation for details on priorities.

- keepalive => $seconds

    Enable TCP keepalive with the specified interval in seconds. When enabled,
    the OS will periodically send probes on idle connections to detect dead peers.
    0 means disabled (default). Recommended for long-lived connections behind
    NAT gateways or firewalls.

- prefer\_ipv4 => $bool

    Prefer IPv4 addresses when resolving hostnames. Mutually exclusive with
    `prefer_ipv6`.

README.md  view on Meta::CPAN

Disconnect from redis-server. Safe to call when already disconnected.
Stops any pending reconnect timer, so explicit disconnect prevents automatic
reconnection. Triggers the `on_disconnect` callback when disconnecting
from an active connection. When called while already disconnected, clears
any waiting commands (e.g., preserved by `resume_waiting_on_reconnect`),
invoking their callbacks with a "disconnected" error (`on_disconnect`
does not fire in this case).
This method is usable for exiting event loop.

## is\_connected

Returns true (1) if a connection context is active (including while the
connection is being established), false (0) otherwise.

## has\_ssl

Class method. Returns true (1) if the module was built with TLS support,
false (0) otherwise.

    if (EV::Redis->has_ssl) {
        # TLS connections are available
    }

## connect\_timeout(\[$ms\])

Get or set the connection timeout in milliseconds. Returns the current value,
or undef if not set. Can also be set via constructor.

## command\_timeout(\[$ms\])

Get or set the command timeout in milliseconds. Returns the current value,
or undef if not set. Can also be set via constructor. When changed while
connected, takes effect immediately on the active connection.

## on\_error(\[$cb->($errstr)\])

Set error callback. With a CODE reference argument, replaces the handler
and returns the new handler. With `undef` or without arguments, clears
the handler and returns undef.

**Note:** Calling without arguments clears the handler. There is no way to
read the current handler without clearing it. This applies to all handler
methods (`on_error`, `on_connect`, `on_disconnect`, `on_push`).

## on\_connect(\[$cb->()\])

Set connect callback. With a CODE reference argument, replaces the handler
and returns the new handler. With `undef` or without arguments, clears
the handler and returns undef.

## on\_disconnect(\[$cb->()\])

Set disconnect callback, called on both normal and error disconnections.
With a CODE reference argument, replaces the handler and returns the new
handler. With `undef` or without arguments, clears the handler and
returns undef.

## on\_push(\[$cb->($reply)\])

Set RESP3 push callback for server-initiated messages (Redis 6.0+).
The callback receives the decoded push message as an array reference.
With a CODE reference argument, replaces the handler and returns the new
handler. With `undef` or without arguments, clears the handler and
returns undef. When changed while connected, takes effect immediately.

    $redis->on_push(sub {
        my ($msg) = @_;
        # $msg is an array ref, e.g. ['invalidate', ['key1', 'key2']]
    });

## reconnect($enable, $delay\_ms, $max\_attempts)

Configure automatic reconnection.

    $redis->reconnect(1);                    # enable with defaults (1s delay, unlimited)
    $redis->reconnect(1, 0);                 # enable with immediate reconnect
    $redis->reconnect(1, 2000);              # enable with 2 second delay
    $redis->reconnect(1, 1000, 5);           # enable with 1s delay, max 5 attempts
    $redis->reconnect(0);                    # disable

`$delay_ms` defaults to 1000 (1 second). 0 means immediate reconnect.
`$max_attempts` defaults to 0 (unlimited).

When enabled, the client will automatically attempt to reconnect on connection
failure or unexpected disconnection. Intentional `disconnect()` calls will
not trigger reconnection.

## reconnect\_enabled

Returns true (1) if automatic reconnection is enabled, false (0) otherwise.

## pending\_count

Returns the number of commands sent to Redis awaiting responses.
Persistent commands (subscribe, psubscribe, ssubscribe, monitor) are not
included in this count.
When called from inside a command callback, the count includes the
current command (it is decremented after the callback returns).

## waiting\_count

Returns the number of commands queued locally (not yet sent to Redis).
These are commands that exceeded the `max_pending` limit.

## max\_pending($limit)

Get or set the maximum number of concurrent commands sent to Redis.
Persistent commands (subscribe, psubscribe, ssubscribe, monitor) are not
subject to this limit.
0 means unlimited (default). When the limit is reached, additional commands
are queued locally and sent as responses arrive.

## waiting\_timeout($ms)

Get or set the maximum time in milliseconds a command can wait in the local queue.
Commands exceeding this timeout are cancelled with "waiting timeout" error.
0 means unlimited (default). Returns the current value as an integer (0 when unset).

## resume\_waiting\_on\_reconnect($bool)

Get or set whether waiting commands are preserved on disconnect and resumed