IO::Async::Connector(3pm)				User Contributed Perl Documentation				 IO::Async::Connector(3pm)

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
";
	      ...
	   },

	   on_resolve_error => sub { die "Cannot resolve - $_[-1]
"; },
	   on_connect_error => sub { die "Cannot connect - $_[0] failed $_[-1]
"; },
	);

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>

perl v5.14.2							    2012-10-24						 IO::Async::Connector(3pm)