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]\n"; },
           on_listen_error  => sub { print STDERR "Cannot listen\n"; },
        );

        $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]\n"; },
           on_listen_error  => sub { print STDERR "Cannot listen\n"; },
        );

        $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 | $handle
       Invoked whenever a new client connects to the socket.

       If neither "handle_constructor" nor "handle_class" parameters are set, this will be
       invoked with the new client socket directly. If a handle constructor or class are set,
       this will be invoked with the newly-constructed handle, having the new socket already
       configured onto it.

   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.

       This is now vaguely deprecated in favour of using "on_accept" with a handle constructor or
       class.

   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.

       This is now vaguely deprecated in favour of using "on_accept" with a handle constructor or
       class.

   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.

       handle_constructor => CODE
               Optional. If defined, gives a CODE reference to be invoked every time a new client
               socket is accepted from the listening socket. It is passed the listener object
               itself, and is expected to return a new instance of "IO::Async::Handle" or a
               subclass, used to wrap the new client socket.

                $handle = $handle_constructor->( $listener )

       handle_class => STRING
               Optional. If defined and "handle_constructor" isn't, then new wrapper handles are
               constructed by invoking the "new" method on the given class name, passing in no
               additional parameters.

                $handle = $handle_class->new()

       acceptor => STRING|CODE
               Optional. If defined, gives the name of a method or a CODE reference to use to
               implement the actual accept behaviour. This will be invoked as:

                $listener->acceptor( $socket ) ==> $accepted

                $listener->acceptor( $socket, handle => $handle ) ==> $handle

               It is invoked with the listening socket as its its argument, and optionally an
               "IO::Async::Handle" instance as a named parameter, and is expected to return a
               "Future" that will eventually yield the newly-accepted socket or handle instance,
               if such was provided.

METHODS

   $acceptor = $listener->acceptor
       Returns the currently-set "acceptor" method name or code reference. This may be of
       interest to Loop "listen" extension methods that wish to extend or wrap it.

   $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 and arranges for the acceptor callback to be
       invoked each time a new connection is accepted on the socket.

       Most parameters given to this method are passed into the "listen" method of the
       IO::Async::Loop object. In addition, the following arguments are also recognised directly:

       on_listen => CODE
               Optional. A callback that is invoked when the listening socket is ready.  Similar
               to that on the underlying loop method, except it is passed the listener object
               itself.

                $on_listen->( $listener )

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 - $!\n";

        $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>