NAME

Linux::Event::Connect - Nonblocking outbound socket connect for Linux::Event

SYNOPSIS

use v5.36;
use Linux::Event;
use Linux::Event::Connect;

my $loop = Linux::Event->new;

my $req = Linux::Event::Connect->new(
  loop => $loop,

  host => '127.0.0.1',
  port => 1234,

  timeout_s => 5,

  on_connect => sub ($req, $fh, $data) {
    # $fh is a connected nonblocking socket.
    # You own the filehandle and must close it.
  },

  on_error => sub ($req, $errno, $data) {
    # Connect failed. $errno is numeric.
    # $! is not modified; set it if you want a message.
    #   local $! = $errno;
  },
);

$loop->run;

DESCRIPTION

Linux::Event::Connect performs an outbound TCP or Unix-domain connect using a nonblocking socket and a Linux::Event watcher.

This module is intentionally small:

• One request object per connect attempt

  The request manages the nonblocking socket, a write-watch while the connect is in progress, and an optional timeout.

• No hidden globals

  All state is carried by the request object.

• Composable

  On success you receive a connected filehandle which can be wrapped by Linux::Event::Stream (if you use it) or watched directly with $loop->watch(...).

CONSTRUCTOR

new

my $req = Linux::Event::Connect->new(%args);

Creates and starts a connect request immediately. Unknown keys are fatal.

Common options

• loop (required)

  A Linux::Event loop instance.

• on_connect (optional)

  on_connect => sub ($req, $fh, $data) { ... }

  Invoked once when the socket is connected. The callback receives ownership of $fh (it will not be closed by the request).

• on_error (optional)

  on_error => sub ($req, $errno, $data) { ... }

  Invoked once on failure with a numeric $errno. The request will tear down its watcher/timeout and close any in-progress socket before calling on_error.

• data (optional)

  Arbitrary user data passed through to callbacks as the last argument.

• timeout_s (optional)

  A numeric number of seconds. If set, the request fails with ETIMEDOUT when the timeout expires.

• nonblocking (optional)

  If provided, must be true. This module only supports nonblocking connects.

Address modes

Exactly one address mode is required.

host/port mode

host => $host, port => $port

port must be an integer in the range 0..65535.

If host is an IPv4 or IPv6 literal, the address is packed directly and no resolver is invoked.

If host is a hostname, this module calls getaddrinfo synchronously to produce one or more candidate sockaddrs. Synchronous resolution may block; see "PERFORMANCE NOTES".

Keys forbidden in host/port mode: family, sockaddr, unix, type, proto.

unix mode

unix => '/path/to.sock'

Connects to a Unix-domain stream socket path.

Keys forbidden in unix mode: host, port, sockaddr, family, type, proto.

sockaddr mode

sockaddr => $packed_sockaddr, family => $AF_*

Uses a caller-supplied packed sockaddr and explicit address family. In this mode family is required and is not inferred.

Keys forbidden in sockaddr mode: host, port, unix, type, proto.

METHODS

cancel

$req->cancel;

Cancels a pending request. No callbacks are invoked. After cancel, the request is inert and will not perform further work.

is_pending / is_done

my $bool = $req->is_pending;
my $bool = $req->is_done;

Convenience accessors for the completion state.

fh

my $fh = $req->fh;

Returns the in-progress filehandle while the request is pending, or undef after completion/cancel.

errno

my $errno = $req->errno;

Returns the last error number seen by the request (most useful after failure).

gai_error

my $str = $req->gai_error;

If hostname resolution via getaddrinfo fails, this returns a stored string describing the resolver failure.

CALLBACK BEHAVIOR

Callbacks are invoked at most once.

Before invoking a callback, the request tears down its internal watcher and timeout. This prevents double-callbacks and keeps re-entrant loop activity safe.

PERFORMANCE NOTES

• IP literals avoid getaddrinfo

  IPv4/IPv6 literals are detected via inet_pton and do not call getaddrinfo.

• Hostnames may block

  Hostname resolution uses synchronous getaddrinfo and may block. For strict nonblocking behavior in all cases, use sockaddr mode with a pre-resolved address or provide an IP literal in host/port mode.

• Candidate fallback

  When multiple candidate sockaddrs are produced (for example, IPv6 then IPv4), Connect will try them in order until one connects or all fail.

SEE ALSO

Linux::Event, Linux::Event::Stream, Socket

LICENSE

Same terms as Perl itself.

cpanm Linux::Event::Connect

perl -MCPAN -e shell
install Linux::Event::Connect