IO::Async::Listener - listen on network sockets for incoming connections
IO::Async::Listener
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->loop_forever;
This object can also be used indirectly via an IO::Async::Loop:
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->loop_forever;
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.
listen
resolve
The following events are invoked, either using subclass methods or CODE references in parameters:
Invoked whenever a new client connects to the socket.
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_accept
Similar to on_stream, but constructs an instance of IO::Async::Socket. This is most useful for SOCK_DGRAM or SOCK_RAW sockets.
on_stream
SOCK_DGRAM
SOCK_RAW
The following named parameters may be passed to new or configure:
new
configure
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.
The IO handle containing an existing listen-mode socket.
Returns the sockname of the underlying listening socket
sockname
Returns the socket address family of the underlying listening socket
Returns the socket type of the underlying listening socket
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:
%params
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
getaddrinfo
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::Loop's extract_addrinfo method. See also the EXAMPLES section.
extract_addrinfo
EXAMPLES
In named resolver mode, the %params hash takes the following keys:
The service name to listen on.
The hostname to listen on. Optional. Will listen on all addresses if not supplied.
Optional. Other arguments to pass along with host and service to the getaddrinfo() call.
host
service
getaddrinfo()
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.
'stream'
'dgram'
'raw'
SOCK_STREAM
use Socket
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.
on_error
In either case, the following keys are also taken:
Optional. A callback that is invoked when the listening socket is ready.
$on_listen->( $listener )
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, then bind(), then sockopt(), then finally socket().
listen()
bind()
sockopt()
socket()
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, $! );
Optional. The queue size to pass to the listen() calls. If not supplied, then 3 will be given instead.
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.
SO_REUSEADDR
As a convenience, it also supports a handle argument, which is passed directly to configure.
handle
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->loop_forever;
The addr or addrs parameters should contain a definition of a plain socket address in a form that the IO::Async::Loop extract_addrinfo method can use.
addrs
This example shows how to use the Socket functions to construct one for TCP port 8001 on address 10.0.0.1:
Socket
$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", }, ... );
Paul Evans <leonerd@leonerd.org.uk>
To install IO::Async, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Async
CPAN shell
perl -MCPAN -e shell install IO::Async
For more information on module installation, please visit the detailed CPAN module installation guide.