view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        numeric IPs.

    path => $str
        Unix socket path. Mutually exclusive with "host".

    loop => $ev_loop
        EV loop to attach to. Default: "EV::default_loop".

    priority => $num (-2 to +2)
        EV watcher priority. Higher = serviced before other EV watchers.

    keepalive => $seconds
        TCP keepalive idle time. Set to 0 to disable. Ignored on Unix
        sockets.

   Timeouts and flow control
    connect_timeout => $ms
        Abort an in-progress non-blocking connect after this many
        milliseconds. 0 = no timeout (default). Applies to any connect that
        does not complete immediately (including unix sockets under rare
        kernel backlog conditions); immediately-completing connects finish
        on the next event loop iteration without arming this timer.

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

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

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

    resume_waiting_on_reconnect => $bool
        If true, the waiting queue survives a disconnect and is replayed on
        reconnect. Default: false.

   Reconnect
    reconnect => $bool
        Enable automatic reconnection on transport errors.

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

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

   Authentication
    username => $str
    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 "-S"
        flag.

   Event handlers
    on_error => $cb->($errstr)
        Connection-level error callback. Default: write the message to
        "STDERR" via "warn". Callbacks are run under "G_EVAL", so any "die"
        in a custom handler is demoted to a warning -- use an explicit flag
        if you need to terminate.

    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 "new" / "connect" /
        "connect_unix" -- so a handler installed right after the constructor
        still fires.

    on_disconnect => $cb->()
        Fires after a disconnect, after pending callbacks have been
        cancelled. For server-initiated close, this fires before "on_error".

LIFECYCLE
  connect($host, [$port])
    Connect to a TCP host. Port defaults to 11211. Stops any pending
    auto-reconnect timer and clears any prior "path" setting.

  connect_unix($path)
    Connect via Unix domain socket. Stops any pending auto-reconnect timer
    and clears any prior "host" setting.

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

  is_connected
    Returns true while a session is established 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 "not connected".

  quit([$cb])
    Send a memcached "QUIT" and let the server close the connection. Treated
    as an intentional disconnect: "on_disconnect" fires when the server
    closes, but "on_error" does not, and auto-reconnect is suppressed.

STORAGE COMMANDS
    Each command's callback receives "($result, $err)". $result is 1 on
    success.

  set($key, $value, [$expiry, [$flags,]] [$cb])
    Store unconditionally. Without $cb this becomes fire-and-forget (SETQ):
    no response is received and any server-side failure is silently dropped.

  add($key, $value, [$expiry, [$flags,]] [$cb])
    Store only if the key does not exist. Errors with "EXISTS" if present