NAME

IO::Async::Connector - perform non-blocking socket connections

SYNOPSIS

This object is used indirectly via an IO::Async::Loop:

 use IO::Async::Loop;
 my $loop = IO::Async::Loop->new();

 $loop->connect(
    host     => "www.example.com",
    service  => "http",
    socktype => 'stream',

    on_connected => sub {
       my ( $sock ) = @_;
       print "Now connected via $sock\n";
       ...
    },

    on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
    on_connect_error => sub { print STDERR "Cannot connect\n"; },
 );

DESCRIPTION

This module extends an IO::Async::Loop to give it the ability to create socket connections in a non-blocking manner.

There are two modes of operation. Firstly, a list of addresses can be provided which will be tried in turn. Alternatively as a convenience, if a host and service name are provided instead of a list of addresses, these will be resolved using the underlying loop's resolve() method into the list of addresses.

When attempting to connect to any among a list of addresses, there may be failures among the first attempts, before a valid connection is made. For example, the resolver may have returned some IPv6 addresses, but only IPv4 routes are valid on the system. In this case, the first connect() syscall will fail. This isn't yet a fatal error, if there are more addresses to try, perhaps some IPv4 ones.

For this reason, the error reporting cannot report which failure is responsible for the failure to connect. On success, the on_connected continuation is invoked with a connected socket. When all addresses have been tried and failed, on_connect_error is invoked, though no error string can be provided, as there isn't a "clear winner" which is responsible for the failure.

To be aware of individual failures, the optional on_fail callback can be used. This will be invoked on each individual socket() or connect() failure, which may be useful for debugging or logging.

Because this module simply uses the getaddrinfo resolver, it will be fully IPv6-aware if the underlying platform's resolver is. This allows programs to be fully IPv6-capable.

METHODS

$loop->connect( %params )

This method performs a non-blocking connection to a given address or set of addresses, and invokes a continuation when the socket is connected.

In plain address mode, the %params hash takes the following keys:

addrs => ARRAY

Reference to an array of (possibly-multiple) address structures to attempt to connect to. Each should be in the layout described for addr. Such a layout is returned by the getaddrinfo named resolver.

addr => ARRAY

Shortcut for passing a single address to connect to; it may be passed directly with this key, instead of in another array on its own.

The address (or each element of the addrs array) should be a reference to an array, with at least the following elements:

 [ $family, $socktype, $protocol, $address ]

The first three arguments will be passed to a socket() call and, if successful, the fourth to a connect() call on the resulting socket. Any trailing elements will be ignored. Note that $address must be a packed socket address, such as returned by pack_sockaddr_in or pack_sockaddr_un. See also the EXAMPLES section,

on_connected => CODE

A continuation that is invoked on a successful connect() call to a valid socket. It will be passed the connected socket handle, as an IO::Socket object.

 $on_connected->( $handle )

on_stream => CODE

An alternative to on_connected, a continuation that is passed an instance of IO::Async::Stream when the socket is connected. This is provided as a convenience for the common case that a Stream object is required as the transport for a Protocol object.

 $on_stream->( $stream )

on_socket => CODE

Similar to on_stream, but constructs an instance of IO::Async::Socket. This is most useful for SOCK_DGRAM or SOCK_RAW sockets.

 $on_socket->( $socket )

on_connect_error => CODE

A continuation that is invoked after all of the addresses have been tried, and none of them succeeded. Because there is no one error message that stands out as particularly noteworthy, none is given to this continuation. To track individual errors, see the on_fail callback.

on_fail => CODE

Optional. After an individual socket() or connect() syscall has failed, this callback is invoked to inform of the error. It is passed the name of the syscall that failed, the arguments that were passed to it, and the error it generated. I.e.

 $on_fail->( "socket", $family, $socktype, $protocol, $! );

 $on_fail->( "connect", $sock, $address, $! );

Because of the "try all" nature when given a list of multiple addresses, this callback may be invoked multiple times, even before an eventual success.

When performing the resolution step too, the addrs or addr keys are ignored, and instead the following keys are taken:

host => STRING

service => STRING

The hostname and service name to connect to.

family => INT

socktype => INT

protocol => INT

flags => INT

Optional. Other arguments to pass along with host and service to the getaddrinfo() call.

socktype => STRING

Optionally may instead be one of the values 'stream', 'dgram' or 'raw' to stand for SOCK_STREAM, SOCK_DGRAM or SOCK_RAW. This utility is provided to allow the caller to avoid a separate use Socket only for importing these constants.

on_resolve_error => CODE

A continuation that is invoked when the name resolution attempt fails. This is invoked in the same way as the on_error continuation for the resolve method.

It is sometimes necessary to pass the socktype hint to the resolver when resolving the host/service names into an address, as some OS's getaddrinfo functions require this hint.

EXAMPLES

Passing Packed Socket Addresses

The addr or addrs parameters should contain a packed socket address. This example shows how to use the Socket functions to construct one for TCP port 8001 on address 10.0.0.1:

 use Socket qw( PF_INET SOCK_STREAM pack_sockaddr_in inet_aton );

 ...

 $loop->connect(
    addr => [
       PF_INET,
       SOCK_STREAM,
       0, # Don't need to supply a protocol as kernel will do that
       pack_sockaddr_in( 8001, inet_aton( "10.0.0.1" ) ),
    ],
    ...
 );

This example shows another way to connect to a UNIX socket at echo.sock.

 use Socket qw( PF_UNIX SOCK_STREAM pack_sockaddr_un );

 ...

 $loop->connect(
    addr => [
       PF_UNIX,
       SOCK_STREAM,
       0, # Don't need to supply a protocol as kernel will do that
       pack_sockaddr_un( "echo.sock" ),
    ],
    ...
 );

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>