view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

`$g->connect` / `$g->connect_unix` later.

All keys default to `undef` unless noted. Booleans accept any Perl
truthy value.

### Connection

- `host => $str`
- `port => $int`

    TCP host and port. Default port: `4730`. Mutually exclusive with
    `path`.

    Name resolution is currently synchronous: a non-numeric `host` is
    passed straight to `getaddrinfo`, which can block the event loop
    for the system resolver timeout. Pass an IP literal (or pre-resolve
    once) to keep reconnect cycles fully non-blocking.

- `path => $str`

    Unix-domain socket path. Mutually exclusive with `host`.

    Note that a `connect(2)` to a unix socket completes inline, so the
    connection is fully established (and `on_connect` has already fired)
    before `new` returns — a `$g->on_connect(...)` assigned after
    construction will never fire for it. Pass `on_connect` to the
    constructor instead (the same can theoretically happen for a TCP
    connect that completes immediately).

- `loop => $ev_loop`

    EV loop to attach to. Default: `EV::default_loop`.

- `priority => $num`

    EV watcher priority in `-2 .. +2`. Higher = serviced before other
    EV watchers in the same iteration. Default `0`.

- `keepalive => $seconds`

    TCP keepalive idle interval. `0` disables. Ignored on Unix sockets.

### Timeouts

- `connect_timeout => $ms`

    Abort an in-progress non-blocking connect after this many ms. `0`
    = no timeout (default).

- `command_timeout => $ms`

    Per-request timeout. The request at the head of the pending queue is
    given this many ms from the moment it is written to the socket; if it
    is still unanswered when its budget expires, the connection is torn
    down with `"command timeout"`. The budget is independent of
    unrelated traffic: other packets arriving meanwhile neither extend
    the head request's budget nor shorten it, and once the head is
    answered the next request's own budget applies. A slow reply that
    keeps dribbling in is therefore safe as long as the request completes
    within its budget — and a genuinely stuck request dies on schedule
    even on an otherwise busy connection. `0` = no timeout (default).

### Reconnect

- `reconnect => $bool`

    Enable automatic reconnect on transport errors.

- `reconnect_delay => $ms`

    Wait this many ms before each reconnect attempt. Default `1000`.
    The delay is always honored via a timer, so even `0` 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).

After a reconnect, all worker `CAN_DO`/`CAN_DO_TIMEOUT`
registrations and the `exceptions` option are re-sent
automatically.

### Worker / option flags

- `exceptions => $bool`

    If true, the `exceptions` option is sent on every connect, so
    foreground clients receive `WORK_EXCEPTION` packets. For workers,
    this also enables forwarding `die` messages from sync callbacks
    as exceptions instead of the `WORK_FAIL` (`WORK_EXCEPTION` is
    terminal at the server; sending both would earn a `JOB_NOT_FOUND`).

- `client_id => $str`

    Sent as `SET_CLIENT_ID` on every connect. Visible in the admin
    `workers` output.

- `grab_unique => $bool`

    If true, the worker GRAB loop uses `GRAB_JOB_UNIQ`, so the job
    object exposes the unique key supplied by the submitter.

### Event handlers

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

    Connection-level error callback. Default: `warn`. User callbacks
    are run under `G_EVAL`.

- `on_connect => $cb->()`

    Fires once the TCP/Unix connection is fully established and the
    client has enqueued its options and worker-function CAN\_DOs.
    Those packets sit ahead of any user submissions made from inside
    the callback — so submitting a job here is safe even though the
    ability registrations haven't yet hit the socket.

    For unix sockets (`path`) the connect completes inline inside
    `new`, so this callback fires before `new` returns — assign it via
    the constructor, not after (see `path`).