view release on metacpan or  search on metacpan

README  view on Meta::CPAN

   Connection
    host => $str
    port => $int (default 11211)
        TCP host and port. Mutually exclusive with "path".

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

    waiting_timeout => $ms
        Maximum time a command may sit in the waiting queue before its
        callback fires with "waiting timeout". 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). Pre-connect commands
        sit in the waiting queue until SASL completes. 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". 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.

  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
    (the server may append a message, e.g. "EXISTS: Data exists for key.").