IO::Async::Listener(3)User Contributed Perl DocumentatioIO::Async::Listener(3)NAME
"IO::Async::Listener" - listen on network sockets for incoming
connections
SYNOPSIS
use IO::Async::Listener;
use IO::Async::Stream;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new();
my $listener = IO::Async::Listener->new(
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;
},
) );
},
);
$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.
Callbacks
If the "on_accept" key is supplied to the constructor, it should
contain a CODE reference to a callback function to be invoked when
a new client connects to the socket. It is passed an "IO::Socket"
reference to the newly accepted socket:
$on_accept->( $self, $clientsocket )
Base Class
If a subclass is built, then it can override the "on_accept"
method.
$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.
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.
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.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.14.2 2010-06-09 IO::Async::Listener(3)
