Linux Certif

Toute la documentation sur la certification Linux LPI

IO::Async::Listener.3pm

NAME

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

SYNOPSIS

This object is used indirectly via an "IO::Async::Loop":

  use Socket qw( SOCK_STREAM );
 
  use IO::Async::Stream;
 
  use IO::Async::Loop;
  my $loop = IO::Async::Loop->new();
 
  $loop->listen(
     service  => "echo",
     socktype => SOCK_STREAM,
 
     on_accept => sub {
        my ( $newclient ) = @_;
 
        $loop->add( IO::Async::Stream->new(
           handle => $newclient,
 
           on_read => sub {
              my ( $self, $buffref, $closed ) = @_;
              $self->write( $$buffref );
              $$buffref = "";
              return 0;
           },
        ) );
     },
 
     on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
     on_listen_error  => sub { print STDERR "Cannot listen\n"; },
  );
 
  $loop->loop_forever;
 
 

DESCRIPTION

This module extends an "IO::Async::Loop" to give it the ability to create listening sockets, and accept incoming connections on them.

There are two modes of operation. Firstly, a list of addresses can be provided which will be listened on. Alternatively as a convenience, if a service name is provided instead of a list of addresses, then these will be resolved using the underlying loop's "resolve()" method into a list of addresses.

METHODS

$loop->listen( %params )

This method sets up a listening socket using the addresses given, and will invoke a 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. As a convenience, an existing listening socket can be passed directly instead.

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.

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.

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.

To pass an existing socket handle, the %params hash takes the following keys:

handle => IO

The IO handle containing an existing listen-mode socket.

In either case, the following keys are also taken:

on_accept => CODE

A callback that is invoked whenever a new client connects to the socket. It is passed the new socket handle

  $on_accept->( $clientsocket );
 
 

on_listen => CODE

Optional. A callback that is invoked when the listening socket is ready. Typically this would be used in the name resolver case, in order to inspect the socket's sockname address, or otherwise inspect the filehandle.

  $on_listen->( $listensocket );
 
 

on_notifier => CODE

Optional. A callback that is invoked when a "IO::Async::Handle" object has been constructed around the listening socket, and added to the underlying "IO::Async::Loop" object. Typically this can be used to store a reference to the notifier so that it can later be removed from the loop.

  $on_notifier->( $notifier )
 
 

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.

If more than one address is provided or resolved, then a separate listening socket will be created on each.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>