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¶
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 - $!\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>