view release on metacpan or  search on metacpan

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

immediately (including unix sockets under rare kernel backlog
conditions); immediately-completing connects finish on the next event
loop iteration without arming this timer.

=item command_timeout => $ms

Disconnect with C<"command timeout"> error if no response arrives
within this interval. The timer resets on every response from the
server. 0 = no timeout (default).

=item max_pending => $num

Cap on concurrent in-flight commands. Excess commands are held in a
local waiting queue. 0 = unlimited (default). An C<mget>/C<mgets>
counts as one command against the cap and in
C<pending_count>/C<waiting_count>; its keys are always sent together.
Chunk very large key lists.

=item waiting_timeout => $ms

Maximum time a command may sit in the waiting queue before its callback
fires with C<"waiting timeout">. Expired fire-and-forget commands are
dropped silently. 0 = unlimited (default).

=item resume_waiting_on_reconnect => $bool

If true, the waiting queue survives a disconnect and is replayed on
reconnect. Default: false.

=back

=head3 Reconnect

=over

=item reconnect => $bool

Enable automatic reconnection on transport errors.

=item reconnect_delay => $ms (default 1000)

Delay before each reconnect attempt. The delay is always honored via a
timer; setting it to 0 still defers through the event loop (no
synchronous retry recursion).

=item max_reconnect_attempts => $num

Give up after this many consecutive failures and emit
C<"max reconnect attempts reached">. 0 = unlimited (default).

=back

=head3 Authentication

=over

=item username => $str

=item password => $str

SASL PLAIN credentials. When both are set, the client authenticates
after every successful connect (and reconnect). Commands issued
before authentication completes sit in the waiting queue until SASL
finishes. Requires a memcached build with SASL support and the C<-S>
flag.

=back

=head3 Event handlers

=over

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

Connection-level error callback. Default: write the message to
C<STDERR> via C<warn>. Callbacks are run under C<G_EVAL>, so any
C<die> in a custom handler is demoted to a warning -- use an explicit
flag if you need to terminate.

=item on_connect => $cb->()

Fires once the connection is fully established (after SASL, when
applicable; on SASL auth failure it never fires). Always delivered from
the event loop -- never synchronously from C<new> / C<connect> /
C<connect_unix> -- so a handler installed right after the constructor
still fires.

=item on_disconnect => $cb->()

Fires after a disconnect, after pending callbacks have been cancelled.
For server-initiated close, this fires before C<on_error>.

=back

=head1 LIFECYCLE

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

Connect to a TCP host. Port defaults to 11211. Stops any pending
auto-reconnect timer and clears any prior C<path> setting.

=head2 connect_unix($path)

Connect via Unix domain socket. Stops any pending auto-reconnect timer
and clears any prior C<host> setting.

=head2 disconnect

Disconnect cleanly. Cancels any pending reconnect, drains pending
command callbacks with C<(undef, "disconnected")>, then fires
C<on_disconnect> when a session exists or a connect is in progress.
For an intentional disconnect, C<on_error> does B<not> fire -- that
distinction lets you tell user-initiated teardown from server-side
close.

=head2 is_connected

Returns true while a session is established B<or> in progress (TCP
handshake / SASL exchange). Commands issued in the connecting phase
are queued and sent on completion. Commands issued while neither
connected nor reconnect-pending croak with C<"not connected">.