IO::Async::Connector(3User Contributed Perl DocumentatiIO::Async::Connector(3)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.
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.
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_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.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.14.2 2010-06-09 IO::Async::Connector(3)
