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

NAME

       "IO::Async::Listener" - listen on network sockets for incoming connections

SYNOPSIS

	use IO::Async::Listener;

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

	my $listener = IO::Async::Listener->new(
	   on_stream => sub {
	      my ( undef, $stream ) = @_;

	      $stream->configure(
		 on_read => sub {
		    my ( $self, $buffref, $eof ) = @_;
		    $self->write( $$buffref );
		    $$buffref = "";
		    return 0;
		 },
	      );

	      $loop->add( $stream );
	   },
	);

	$loop->add( $listener );

	$listener->listen(
	   service  => "echo",
	   socktype => 'stream',

	   on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]
"; },
	   on_listen_error  => sub { print STDERR "Cannot listen
"; },
	);

	$loop->run;

       This object can also be used indirectly via an "IO::Async::Loop":

	use IO::Async::Stream;

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

	$loop->listen(
	   service  => "echo",
	   socktype => 'stream',

	   on_stream => sub {
	      ...
	   },

	   on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]
"; },
	   on_listen_error  => sub { print STDERR "Cannot listen
"; },
	);

	$loop->run;

DESCRIPTION

       This subclass of IO::Async::Handle adds behaviour which watches a socket in listening mode, to accept incoming connections on them.

       A Listener can be constructed and given a existing socket in listening mode.  Alternatively, the Listener can construct a socket by calling
       the "listen" method. Either a list of addresses can be provided, or a service name can be looked up using the underlying loop's "resolve"
       method.

EVENTS

       The following events are invoked, either using subclass methods or CODE references in parameters:

   on_accept $clientsocket
       Invoked whenever a new client connects to the socket.

   on_stream $stream
       An alternative to "on_accept", this an instance of IO::Async::Stream when a new client connects. This is provided as a convenience for the
       common case that a Stream object is required as the transport for a Protocol object.

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

   on_accept_error $socket, $errno
       Optional. Invoked if the "accept" syscall indicates an error (other than "EAGAIN" or "EWOULDBLOCK"). If not provided, failures of "accept"
       will simply be ignored.

PARAMETERS

       The following named parameters may be passed to "new" or "configure":

       on_accept => CODE
       on_stream => CODE
       on_socket => CODE
	       CODE reference for the event handlers. Because of the mutually-exclusive nature of their behaviour, only one of these may be set at
	       a time. Setting one will remove the other two.

       handle => IO
	       The IO handle containing an existing listen-mode socket.

METHODS

   $name = $listener->sockname
       Returns the "sockname" of the underlying listening socket

   $family = $listener->family
       Returns the socket address family of the underlying listening socket

   $socktype = $listener->socktype
       Returns the socket type of the underlying listening socket

   $listener->listen( %params )
       This method sets up a listening socket using the addresses given, and will invoke the "on_accept" callback each time a new connection is
       accepted on the socket. Addresses may be given directly, or they may be looked up using the system's name resolver.

       If multiple addresses are given, or resolved from the service and hostname, then each will be attempted in turn until one succeeds.

       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 listen on. 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 listen on; it may be passed directly with this key, instead of in another array of its
	       own. This should be in a format recognised by IO::Async::OS's "extract_addrinfo" method. See also the "EXAMPLES" section.

       In named resolver mode, the %params hash takes the following keys:

       service => STRING
	       The service name to listen on.

       host => STRING
	       The hostname to listen on. Optional. Will listen on all addresses if not supplied.

       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.

       In either case, the following keys are also taken:

       on_listen => CODE
	       Optional. A callback that is invoked when the listening socket is ready.

		$on_listen->( $listener )

       on_listen_error => CODE
	       A continuation this 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 listen(2) syscall are considered
	       most significant, then bind(2), then sockopt(2), then finally socket(2).

       on_fail => CODE
	       Optional. A callback that is invoked if a syscall fails while attempting to create a listening sockets. It is passed the name of
	       the syscall that failed, the arguments that were passed to it, and the error generated. I.e.

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

		$on_fail->( "sockopt", $sock, $optname, $optval, $! );

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

		$on_fail->( "listen", $sock, $queuesize, $! );

       queuesize => INT
	       Optional. The queue size to pass to the listen(2) calls. If not supplied, then 3 will be given instead.

       reuseaddr => BOOL
	       Optional. If true or not supplied then the "SO_REUSEADDR" socket option will be set. To prevent this, pass a false value such as 0.

       v6only => BOOL
	       Optional. If defined, sets or clears the "IPV6_V6ONLY" socket option on "PF_INET6" sockets. This option disables the ability of
	       "PF_INET6" socket to accept connections from "AF_INET" addresses. Not all operating systems allow this option to be disabled.

       As a convenience, it also supports a "handle" argument, which is passed directly to "configure".

EXAMPLES

   Listening on UNIX Sockets
       The "handle" argument can be passed an existing socket already in listening mode, making it possible to listen on other types of socket
       such as UNIX sockets.

	use IO::Async::Listener;
	use IO::Socket::UNIX;

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

	my $listener = IO::Async::Listener->new(
	   on_stream => sub {
	      my ( undef, $stream ) = @_;

	      $stream->configure(
		 on_read => sub {
		    my ( $self, $buffref, $eof ) = @_;
		    $self->write( $$buffref );
		    $$buffref = "";
		    return 0;
		 },
	      );

	      $loop->add( $stream );
	   },
	);

	$loop->add( $listener );

	my $socket = IO::Socket::UNIX->new(
	   Local => "echo.sock",
	   Listen => 1,
	) or die "Cannot make UNIX socket - $!
";

	$listener->listen(
	   handle => $socket,
	);

	$loop->run;

   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:

	$listener->listen(
	   addr => {
	      family   => "inet",
	      socktype => "stream",
	      port     => 8001,
	      ip       => "10.0.0.1",
	   },
	   ...
	);

       This example shows another way to listen on a UNIX socket, similar to the earlier example:

	$listener->listen(
	   addr => {
	      family   => "unix",
	      socktype => "stream",
	      path     => "echo.sock",
	   },
	   ...
	);

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

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