.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Async::Connector 3pm"
.TH IO::Async::Connector 3pm "2012-10-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"IO::Async::Connector" \- perform non\-blocking socket connections
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This object is used indirectly via an \f(CW\*(C`IO::Async::Loop\*(C'\fR:
.PP
.Vb 2
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& $loop\->connect(
\&    host     => "www.example.com",
\&    service  => "http",
\&    socktype => \*(Aqstream\*(Aq,
\&
\&    on_connected => sub {
\&       my ( $sock ) = @_;
\&       print "Now connected via $sock\en";
\&       ...
\&    },
\&
\&    on_resolve_error => sub { die "Cannot resolve \- $_[\-1]\en"; },
\&    on_connect_error => sub { die "Cannot connect \- $_[0] failed $_[\-1]\en"; },
\& );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module extends an \f(CW\*(C`IO::Async::Loop\*(C'\fR to give it the ability to create
socket connections in a non-blocking manner.
.PP
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 \f(CW\*(C`resolve\*(C'\fR method into the list of
addresses.
.PP
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 \f(CWconnect(2)\fR syscall
will fail. This isn't yet a fatal error, if there are more addresses to try,
perhaps some IPv4 ones.
.PP
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 \f(CW\*(C`on_fail\*(C'\fR callback can be used. This will be invoked on each
individual \f(CWsocket(2)\fR or \f(CWconnect(2)\fR failure, which may be useful for
debugging or logging.
.PP
Because this module simply uses the \f(CW\*(C`getaddrinfo\*(C'\fR resolver, it will be fully
IPv6\-aware if the underlying platform's resolver is. This allows programs to
be fully IPv6\-capable.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$loop\->connect( %params )"
.el .SS "\f(CW$loop\fP\->connect( \f(CW%params\fP )"
.IX Subsection "$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.
.PP
In plain address mode, the \f(CW%params\fR hash takes the following keys:
.IP "addrs => \s-1ARRAY\s0" 8
.IX Item "addrs => ARRAY"
Reference to an array of (possibly-multiple) address structures to attempt to
connect to. Each should be in the layout described for \f(CW\*(C`addr\*(C'\fR. Such a layout
is returned by the \f(CW\*(C`getaddrinfo\*(C'\fR named resolver.
.IP "addr => \s-1HASH\s0 or \s-1ARRAY\s0" 8
.IX Item "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 \f(CW\*(C`extract_addrinfo\*(C'\fR method. See also
the \f(CW\*(C`EXAMPLES\*(C'\fR section.
.IP "local_addrs => \s-1ARRAY\s0" 8
.IX Item "local_addrs => ARRAY"
.PD 0
.IP "local_addr => \s-1HASH\s0 or \s-1ARRAY\s0" 8
.IX Item "local_addr => HASH or ARRAY"
.PD
Optional. Similar to the \f(CW\*(C`addrs\*(C'\fR or \f(CW\*(C`addr\*(C'\fR parameters, these specify a local
address or set of addresses to \f(CWbind(2)\fR the socket to before
\&\f(CWconnect(2)\fRing it.
.IP "on_connected => \s-1CODE\s0" 8
.IX Item "on_connected => CODE"
A continuation that is invoked on a successful \f(CW\*(C`connect(22)\*(C'\fR call to a valid
socket. It will be passed the connected socket handle, as an \f(CW\*(C`IO::Socket\*(C'\fR
object.
.Sp
.Vb 1
\& $on_connected\->( $handle )
.Ve
.IP "on_stream => \s-1CODE\s0" 8
.IX Item "on_stream => CODE"
An alternative to \f(CW\*(C`on_connected\*(C'\fR, 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.
.Sp
.Vb 1
\& $on_stream\->( $stream )
.Ve
.IP "on_socket => \s-1CODE\s0" 8
.IX Item "on_socket => CODE"
Similar to \f(CW\*(C`on_stream\*(C'\fR, but constructs an instance of IO::Async::Socket.
This is most useful for \f(CW\*(C`SOCK_DGRAM\*(C'\fR or \f(CW\*(C`SOCK_RAW\*(C'\fR sockets.
.Sp
.Vb 1
\& $on_socket\->( $socket )
.Ve
.IP "on_connect_error => \s-1CODE\s0" 8
.IX Item "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
\&\f(CWconnect(2)\fR syscall are considered most significant, then \f(CWbind(2)\fR, then
finally \f(CWsocket(2)\fR.
.Sp
.Vb 1
\& $on_connect_error\->( $syscall, $! )
.Ve
.IP "on_fail => \s-1CODE\s0" 8
.IX Item "on_fail => CODE"
Optional. After an individual \f(CWsocket(2)\fR or \f(CWconnect(2)\fR 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.
.Sp
.Vb 1
\& $on_fail\->( "socket", $family, $socktype, $protocol, $! );
\&
\& $on_fail\->( "bind", $sock, $address, $! );
\&
\& $on_fail\->( "connect", $sock, $address, $! );
.Ve
.Sp
Because of the \*(L"try all\*(R" nature when given a list of multiple addresses, this
callback may be invoked multiple times, even before an eventual success.
.PP
When performing the resolution step too, the \f(CW\*(C`addrs\*(C'\fR or \f(CW\*(C`addr\*(C'\fR keys are
ignored, and instead the following keys are taken:
.IP "host => \s-1STRING\s0" 8
.IX Item "host => STRING"
.PD 0
.IP "service => \s-1STRING\s0" 8
.IX Item "service => STRING"
.PD
The hostname and service name to connect to.
.IP "local_host => \s-1STRING\s0" 8
.IX Item "local_host => STRING"
.PD 0
.IP "local_service => \s-1STRING\s0" 8
.IX Item "local_service => STRING"
.PD
Optional. The hostname and/or service name to \f(CWbind(2)\fR the socket to locally
before connecting to the peer.
.IP "family => \s-1INT\s0" 8
.IX Item "family => INT"
.PD 0
.IP "socktype => \s-1INT\s0" 8
.IX Item "socktype => INT"
.IP "protocol => \s-1INT\s0" 8
.IX Item "protocol => INT"
.IP "flags => \s-1INT\s0" 8
.IX Item "flags => INT"
.PD
Optional. Other arguments to pass along with \f(CW\*(C`host\*(C'\fR and \f(CW\*(C`service\*(C'\fR to the
\&\f(CW\*(C`getaddrinfo\*(C'\fR call.
.IP "socktype => \s-1STRING\s0" 8
.IX Item "socktype => STRING"
Optionally may instead be one of the values \f(CW\*(Aqstream\*(Aq\fR, \f(CW\*(Aqdgram\*(Aq\fR or
\&\f(CW\*(Aqraw\*(Aq\fR to stand for \f(CW\*(C`SOCK_STREAM\*(C'\fR, \f(CW\*(C`SOCK_DGRAM\*(C'\fR or \f(CW\*(C`SOCK_RAW\*(C'\fR. This
utility is provided to allow the caller to avoid a separate \f(CW\*(C`use Socket\*(C'\fR only
for importing these constants.
.IP "on_resolve_error => \s-1CODE\s0" 8
.IX Item "on_resolve_error => CODE"
A continuation that is invoked when the name resolution attempt fails. This is
invoked in the same way as the \f(CW\*(C`on_error\*(C'\fR continuation for the \f(CW\*(C`resolve\*(C'\fR
method.
.PP
It is necessary to pass the \f(CW\*(C`socktype\*(C'\fR hint to the resolver when resolving
the host/service names into an address, as some \s-1OS\s0's \f(CW\*(C`getaddrinfo\*(C'\fR functions
require this hint. A warning is emitted if neither \f(CW\*(C`socktype\*(C'\fR nor \f(CW\*(C`protocol\*(C'\fR
hint is defined when performing a \f(CW\*(C`getaddrinfo\*(C'\fR lookup. To avoid this warning
while still specifying no particular \f(CW\*(C`socktype\*(C'\fR hint (perhaps to invoke some
OS-specific behaviour), pass \f(CW0\fR as the \f(CW\*(C`socktype\*(C'\fR value.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Passing Plain Socket Addresses"
.IX Subsection "Passing Plain Socket Addresses"
The \f(CW\*(C`addr\*(C'\fR or \f(CW\*(C`addrs\*(C'\fR parameters should contain a definition of a plain
socket address in a form that the IO::Async::OS \f(CW\*(C`extract_addrinfo\*(C'\fR
method can use.
.PP
This example shows how to use the \f(CW\*(C`Socket\*(C'\fR functions to construct one for \s-1TCP\s0
port 8001 on address 10.0.0.1:
.PP
.Vb 9
\& $loop\->connect(
\&    addr => {
\&       family   => "inet",
\&       socktype => "stream",
\&       port     => 8001,
\&       ip       => "10.0.0.1",
\&    },
\&    ...
\& );
.Ve
.PP
This example shows another way to connect to a \s-1UNIX\s0 socket at \fIecho.sock\fR.
.PP
.Vb 8
\& $loop\->connect(
\&    addr => {
\&       family   => "unix",
\&       socktype => "stream",
\&       path     => "echo.sock",
\&    },
\&    ...
\& );
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>