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, $closed ) = @_;
             $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->loop_forever;

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_accept => sub {
       ...
    },

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

 $loop->loop_forever;

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.

This object may be used in one of two ways; with a callback function, or as a base class.

Subclassing

If a subclass is built, then it can override the following methods to handle events:

 $self->on_accept( $clientsocket )

PARAMETERS

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

on_accept => CODE

A callback that is invoked whenever a new client connects to the socket. If not supplied the subclass method will be called instead.

 $on_accept->( $self, $clientsocket )

on_stream => CODE

An alternative to on_accept, a continuation that is passed 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_stream->( $self, $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->( $self, $socket )

handle => IO

The IO handle containing an existing listen-mode socket.

METHODS

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

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 bind() call on the resulting socket. The socket will then be listen()ed to put it into listening mode. Any trailing elements in this array will be ignored. Note that $address must be a packed socket address, such as returned by pack_sockaddr_in or pack_sockaddr_un. 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.

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. Becasue 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. 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() 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.

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, $closed ) = @_;
             $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->loop_forever;

Passing Packed Socket Addresses

The addr or addrs parameters should contain a packed socket address. This example shows how to use the Socket functions to construct one for TCP port 8001 on address 10.0.0.1:

 use Socket qw( PF_INET SOCK_STREAM pack_sockaddr_in inet_aton );

 ...

 $listener->listen(
    addr => [
       PF_INET,
       SOCK_STREAM,
       0, # Don't need to supply a protocol as kernel will do that
       pack_sockaddr_in( 8001, inet_aton( "10.0.0.1" ) ),
    ],
    ...
 );

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

 use Socket qw( PF_UNIX SOCK_STREAM pack_sockaddr_un );

 ...

 $listener->listen(
    addr => [
       PF_UNIX,
       SOCK_STREAM,
       0, # Don't need to supply a protocol as kernel will do that
       pack_sockaddr_un( "echo.sock" ),
    ],
    ...
 );

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm IO::Async

perl -MCPAN -e shell
install IO::Async