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->run;
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->run;
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.
If neither handle_constructor nor handle_class parameters are set, this will be invoked with the new client socket directly. If a handle constructor or class are set, this will be invoked with the newly-constructed handle, having the new socket already configured onto it.
handle_constructor
handle_class
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
This is now vaguely deprecated in favour of using on_accept with a handle constructor or class.
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
Optional. Invoked if the accept syscall indicates an error (other than EAGAIN or EWOULDBLOCK). If not provided, failures of accept will simply be ignored.
accept
EAGAIN
EWOULDBLOCK
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.
Optional. If defined, gives a CODE reference to be invoked every time a new client socket is accepted from the listening socket. It is passed the listener object itself, and is expected to return a new instance of IO::Async::Handle or a subclass, used to wrap the new client socket.
IO::Async::Handle
$handle = $handle_constructor->( $listener )
Optional. If defined and handle_constructor isn't, then new wrapper handles are constructed by invoking the new method on the given class name, passing in no additional parameters.
$handle = $handle_class->new()
Optional. If defined, gives the name of a method or a CODE reference to use to implement the actual accept behaviour. This will be invoked as:
$listener->acceptor( $socket ) ==> $accepted $listener->acceptor( $socket, handle => $handle ) ==> $handle
It is invoked with the listening socket as its its argument, and optionally an IO::Async::Handle instance as a named parameter, and is expected to return a Future that will eventually yield the newly-accepted socket or handle instance, if such was provided.
Future
Returns the currently-set acceptor method name or code reference. This may be of interest to Loop listen extension methods that wish to extend or wrap it.
acceptor
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 and arranges for the acceptor callback to be invoked each time a new connection is accepted on the socket.
Most parameters given to this method are passed into the listen method of the IO::Async::Loop object. In addition, the following arguments are also recognised directly:
Optional. A callback that is invoked when the listening socket is ready. Similar to that on the underlying loop method, except it is passed the listener object itself.
$on_listen->( $listener )
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.
handle
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;
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.
addr
addrs
extract_addrinfo
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.