view release on metacpan or  search on metacpan

lib/EV/Memcached.pm  view on Meta::CPAN

=item host => 'Str'

=item port => 'Int' (default 11211)

Hostname and port. Mutually exclusive with C<path>.

=item path => 'Str'

Unix socket path. Mutually exclusive with C<host>.

=item on_error => $cb->($errstr)

Error callback for connection-level errors. Default: C<die>.

=item on_connect => $cb->()

Called when connection is established.

=item on_disconnect => $cb->()

Called when disconnected.

=item connect_timeout => $ms

Connection timeout in milliseconds. 0 = no timeout (default).
Only applies to non-blocking TCP connects (not Unix sockets
or immediate localhost connections).

=item command_timeout => $ms

Command timeout in milliseconds. When set, if no response is received
within this interval, the connection is terminated with "command timeout"
error. The timer resets on every response from the server. 0 = no timeout
(default).

=item max_pending => $num

Maximum concurrent commands. 0 = unlimited (default).

=item waiting_timeout => $ms

Max time in local queue before cancellation. 0 = unlimited.

=item resume_waiting_on_reconnect => $bool

Keep waiting queue on disconnect for replay after reconnect.

=item reconnect => $bool

Enable automatic reconnection.

=item reconnect_delay => $ms (default 1000)

=item max_reconnect_attempts => $num (0 = unlimited)

=item priority => $num (-2 to +2)

EV watcher priority.

=item keepalive => $seconds

TCP keepalive interval.

=item username => 'Str'

=item password => 'Str'

SASL PLAIN authentication credentials. When both are set, the client
automatically authenticates after connecting (and after each reconnect).
Requires memcached started with C<-S> flag and SASL support compiled in.

=item loop => EV::Loop

EV loop to use. Default: C<EV::default_loop>.

=back

=head2 connect($host, [$port])

Connect to memcached server. Port defaults to 11211.

=head2 connect_unix($path)

Connect via Unix socket.

=head2 disconnect

Disconnect from server. Stops reconnect timer. Pending command callbacks
receive C<(undef, "disconnected")> error. C<on_disconnect> fires after
pending callbacks have been cancelled.

For intentional disconnect, only C<on_disconnect> fires. For
server-initiated close or errors, C<on_disconnect> fires first, then
C<on_error> fires with the reason (e.g., "connection closed by server",
"command timeout"). This lets you distinguish the two cases.

=head2 is_connected

Returns true if connected or connecting.

=head2 get($key, [$cb->($value, $err)])

Retrieve a value. On miss: C<($value, $err)> are both C<undef>.

=head2 gets($key, [$cb->($result, $err)])

Retrieve with metadata. C<$result> is C<{ value, flags, cas }>.

=head2 set($key, $value, [$expiry, [$flags,]] [$cb])

Store a value. Without callback: fire-and-forget.

=head2 add($key, $value, [$expiry, [$flags,]] [$cb])

Store only if key does not exist.

=head2 replace($key, $value, [$expiry, [$flags,]] [$cb])

Store only if key exists.

=head2 cas($key, $value, $cas, [$expiry, [$flags,]] [$cb])

lib/EV/Memcached.pm  view on Meta::CPAN

Send quit command. Server will close connection.

=head2 sasl_auth($username, $password, [$cb])

Authenticate using SASL PLAIN mechanism. Called automatically on
connect when C<username> and C<password> constructor options are set.

    $mc->sasl_auth('user', 'secret', sub {
        my ($result, $err) = @_;
        die "auth failed: $err" if $err;
        # authenticated -- proceed with commands
    });

=head2 sasl_list_mechs([$cb->($mechs, $err)])

Query available SASL mechanisms. Returns a space-separated string
(e.g., C<"PLAIN">).

=head2 reconnect($enable, [$delay_ms], [$max_attempts])

Configure automatic reconnection.

=head2 reconnect_enabled

Returns true if reconnect is enabled.

=head2 connect_timeout([$ms])

Get/set connection timeout in milliseconds.

=head2 command_timeout([$ms])

Get/set command timeout in milliseconds. When a response is received,
the timer resets. If no response arrives within the timeout, the
connection is disconnected with "command timeout" error.

=head2 pending_count

Number of commands awaiting server response.

=head2 waiting_count

Number of commands in local queue (flow control).

=head2 max_pending([$limit])

Get/set concurrent command limit.

=head2 waiting_timeout([$ms])

Get/set local queue timeout.

=head2 resume_waiting_on_reconnect([$bool])

Get/set waiting queue behavior on disconnect.

=head2 priority([$num])

Get/set EV watcher priority (-2 to +2).

=head2 keepalive([$seconds])

Get/set TCP keepalive.

=head2 skip_pending

Cancel all pending command callbacks with C<(undef, "skipped")>.

=head2 skip_waiting

Cancel all waiting command callbacks with C<(undef, "skipped")>.

=head2 on_error([$cb])

=head2 on_connect([$cb])

=head2 on_disconnect([$cb])

Get/set handler callbacks.

=head1 DESTRUCTION BEHAVIOR

When an EV::Memcached object is destroyed while commands are still
pending or waiting, all pending callbacks receive C<(undef, "disconnected")>
and all waiting callbacks likewise.

For predictable cleanup:

    $mc->disconnect;
    undef $mc;

Or cancel callbacks first:

    $mc->skip_pending;
    $mc->skip_waiting;
    $mc->disconnect;

B<Circular references:> If callbacks close over C<$mc>, break the cycle
before the object goes out of scope:

    $mc->on_error(undef);
    $mc->on_connect(undef);
    $mc->on_disconnect(undef);

=head1 BENCHMARKS

Measured on Linux with TCP loopback connection, 100-byte values, Perl 5.40,
memcached 1.6.41 (C<bench/benchmark.pl>):

                         50K cmds    200K cmds
    Pipeline SET           213K        68K ops/sec
    Pipeline GET           216K        67K ops/sec
    Mixed workload         226K        69K ops/sec
    Fire-and-forget SET   1.13M      1.29M ops/sec  (SETQ)
    Multi-get (GETKQ)    1.30M       1.17M ops/sec  (per key)
    Sequential round-trip   41K        38K ops/sec

Fire-and-forget mode (no callback) is roughly 5x faster than callback mode
due to zero Perl-side overhead per command. Multi-get is the fastest path
since quiet commands suppress miss responses.

Callback-based throughput scales inversely with batch size because Perl SV
allocation dominates when many closures are queued at once. In real