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 { die "Cannot resolve - $_[-1]\n"; },
on_connect_error => sub { die "Cannot connect - $_[0] failed $_[-1]\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(2) syscall
will fail. This isn't yet a fatal error, if there are more addresses to try,
perhaps some IPv4 ones.
For this reason, it is possible that the operation eventually succeeds even
though some system calls initially fail. To be aware of individual failures,
the optional "on_fail" callback can be used. This will be invoked on
each individual
socket(2) or
connect(2) 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 => HASH or 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.
This should be in a format recognised by IO::Async::OS's
"extract_addrinfo" method. See also the "EXAMPLES"
section.
- local_addrs => ARRAY
- local_addr => HASH or ARRAY
- Optional. Similar to the "addrs" or
"addr" parameters, these specify a local address or set of
addresses to bind(2) the socket to before connect(2)ing it.
- on_connected => CODE
- A continuation that is invoked on a successful
"connect(22)" 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. It will be passed the most
significant error that occurred, and the name of the operation it occurred
in. Errors from the connect(2) syscall are considered most significant,
then bind(2), then finally socket(2).
$on_connect_error->( $syscall, $! )
- on_fail => CODE
- Optional. After an individual socket(2) or connect(2)
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->( "bind", $sock, $address, $! );
$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.
- local_host => STRING
- local_service => STRING
- Optional. The hostname and/or service name to bind(2) the
socket to locally before connecting to the peer.
- 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 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. A warning is emitted if
neither "socktype" nor "protocol" hint is defined when
performing a "getaddrinfo" lookup. To avoid this warning while still
specifying no particular "socktype" hint (perhaps to invoke some
OS-specific behaviour), pass 0 as the "socktype" value.
EXAMPLES¶
Passing Plain Socket Addresses¶
The "addr" or "addrs" parameters should contain a definition
of a plain socket address in a form that the IO::Async::OS
"extract_addrinfo" method can use.
This example shows how to use the "Socket" functions to construct one
for TCP port 8001 on address 10.0.0.1:
$loop->connect(
addr => {
family => "inet",
socktype => "stream",
port => 8001,
ip => "10.0.0.1",
},
...
);
This example shows another way to connect to a UNIX socket at
echo.sock.
$loop->connect(
addr => {
family => "unix",
socktype => "stream",
path => "echo.sock",
},
...
);
AUTHOR¶
Paul Evans <leonerd@leonerd.org.uk>