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.
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.
PARAMETERS
The following named parameters may be passed to new
or configure
:
- on_accept => CODE
-
CODE reference for the
on_accept
event. - 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 forSOCK_DGRAM
orSOCK_RAW
sockets.$on_socket->( $self, $socket )
- 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 thegetaddrinfo
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 either a hash with the following keys:family, socktype, protocol, addr
or an array, with the following elements:
[ $family, $socktype, $protocol, $address ]
The first three arguments will be passed to a
socket()
call and, if successful, the fourth to abind()
call on the resulting socket. The socket will then belisten()
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 bypack_sockaddr_in
orpack_sockaddr_un
. See also theEXAMPLES
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
andservice
to thegetaddrinfo()
call. - socktype => STRING
-
Optionally may instead be one of the values
'stream'
,'dgram'
or'raw'
to stand forSOCK_STREAM
,SOCK_DGRAM
orSOCK_RAW
. This utility is provided to allow the caller to avoid a separateuse 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 theresolve
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. It will be passed the most significant error that occurred, and the name of the operation it occurred in. Errors from the
listen()
syscall are considered most significant, thenbind()
, thensockopt()
, then finallysocket()
. - 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 => {
family => PF_INET,
socktype => SOCK_STREAM,
addr => 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 => {
family => PF_UNIX,
socktype => SOCK_STREAM,
addr => pack_sockaddr_un( "echo.sock" ),
},
...
);
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>