view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

- 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`.

- prefer\_ipv6 => $bool

    Prefer IPv6 addresses when resolving hostnames. Mutually exclusive with
    `prefer_ipv4`.

- source\_addr => 'Str'

    Local address to bind the outbound connection to. Useful on multi-homed
    servers to select a specific network interface.

- tcp\_user\_timeout => $num\_of\_milliseconds

    Set the TCP\_USER\_TIMEOUT socket option (Linux-specific). Controls how long
    transmitted data may remain unacknowledged before the connection is dropped.
    Helps detect dead connections faster on lossy networks.

- cloexec => $bool

    Set SOCK\_CLOEXEC on the Redis connection socket. Prevents the file descriptor
    from leaking to child processes after fork/exec. Default is enabled.

- reuseaddr => $bool

    Set SO\_REUSEADDR on the Redis connection socket. Allows rebinding to an
    address that is still in TIME\_WAIT state. Default is disabled.

- tls => $bool

    Enable TLS/SSL encryption for the connection. Requires that the module was
    built with TLS support (auto-detected at build time, or forced with
    `EV_REDIS_SSL=1`). Only valid with `host` connections, not `path`.

- tls\_ca => 'Str'

    Path to CA certificate file for server verification. If not specified,
    uses the system default CA store.

- tls\_capath => 'Str'

    Path to a directory containing CA certificate files in OpenSSL-compatible
    format (hashed filenames). Alternative to `tls_ca` for multiple CA certs.

- tls\_cert => 'Str'

    Path to client certificate file for mutual TLS authentication. Must be
    specified together with `tls_key`.

- tls\_key => 'Str'

    Path to client private key file. Must be specified together with `tls_cert`.

README.md  view on Meta::CPAN

    $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
after reconnection. Default is false (waiting commands cancelled on disconnect).

## priority($priority)

Get or set the priority for the underlying libev IO watchers. Higher priority
watchers are invoked before lower priority ones when multiple watchers are
pending. Valid range is -2 (lowest) to +2 (highest), with 0 being the default.
Values outside this range are clamped automatically.
Can be changed at any time, including while connected.

    $redis->priority(1);     # higher priority
    $redis->priority(-1);    # lower priority
    $redis->priority(99);    # clamped to 2
    my $prio = $redis->priority;  # get current priority

## keepalive($seconds)

Get or set the TCP keepalive interval in seconds. When set, the OS sends
periodic probes on idle connections to detect dead peers. 0 means disabled
(default). When set to a positive value while connected, takes effect
immediately. Setting to 0 while connected records the preference for future
connections but does not disable keepalives on the current socket.

## prefer\_ipv4($bool)

Get or set IPv4 preference for DNS resolution. Mutually exclusive with
`prefer_ipv6` (setting one clears the other). Takes effect on the next
connection.

## prefer\_ipv6($bool)

Get or set IPv6 preference for DNS resolution. Mutually exclusive with
`prefer_ipv4` (setting one clears the other). Takes effect on the next
connection.

## source\_addr($addr)

Get or set the local source address to bind to when connecting. This is
useful on multi-homed hosts to control which network interface is used.
Pass `undef` to clear. Takes effect on the next TCP connection (has no
effect on Unix socket connections).

## tcp\_user\_timeout($ms)

Get or set the TCP user timeout in milliseconds. This controls how long
transmitted data may remain unacknowledged before the connection is dropped.
0 means use the OS default. Takes effect on the next connection.

## cloexec($bool)

Get or set the close-on-exec flag for the Redis socket. When enabled, the
socket is automatically closed in child processes after fork+exec. Enabled
by default. Takes effect on the next connection.

## reuseaddr($bool)

Get or set SO\_REUSEADDR on the Redis socket. Allows rebinding to an address
still in TIME\_WAIT state. Disabled by default. Takes effect on the next
connection.

## skip\_waiting

Cancel only waiting (not yet sent) command callbacks. Each callback is invoked
with `(undef, "skipped")`. In-flight commands continue normally.

## skip\_pending

Cancel all pending and waiting command callbacks. Each Perl callback is
invoked immediately with `(undef, "skipped")`. For pending commands,
the internal hiredis tracking entry remains until a reply arrives (which
is then discarded); no second callback fires.

## can($method)

Returns code reference if method is available, undef otherwise.
Methods installed via AUTOLOAD (Redis commands) will return true after first call.

# DESTRUCTION BEHAVIOR

When an EV::Redis object is destroyed (goes out of scope or is explicitly
undefined) while commands are still pending or waiting, hiredis invokes all
pending command callbacks with a disconnect error, and EV::Redis invokes