--- name: "IO::Async::Listener" section: "3pm" platform: "linux" package: "libio-async-perl" version: "0.804-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/IO::Async::Listener" --- # IO::Async::Listener(3pm) listen on network sockets for incoming connections ## NAME "IO::Async::Listener" - listen on network sockets for incoming connections ## SYNOPSIS ``` use Future::AsyncAwait; 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 ); await $listener->listen( service => "echo", socktype => 'stream', ); $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; await $loop->listen( service => "echo", socktype => 'stream', on_stream => sub { ... }, ); $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 \| $handle 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. ### on\_stream $stream An alternative to `"on_accept"`, this 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. This is now vaguely deprecated in favour of using `"on_accept"` with a handle constructor or class. ### 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. This is now vaguely deprecated in favour of using `"on_accept"` with a handle constructor or class. ### 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 be passed to the main `"on_error"` handler. ## 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. ### handle\_constructor =\> CODE 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. ``` $handle = $handle_constructor->( $listener ); ``` This can also be given as a subclass method ``` $handle = $listener->handle_constructor(); ``` ### handle\_class =\> STRING 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(); ``` This can also be given as a subclass method ``` $handle = $listener->handle_class->new; ``` ### acceptor =\> STRING\|CODE 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: ``` ( $accepted ) = await $listener->acceptor( $socket ); ( $handle ) = await $listener->acceptor( $socket, 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. ## METHODS The following methods documented in `"await"` expressions return Future instances. ### acceptor ``` $acceptor = $listener->acceptor; ``` 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. ### sockname ``` $name = $listener->sockname; ``` Returns the `"sockname"` of the underlying listening socket ### family ``` $family = $listener->family; ``` Returns the socket address family of the underlying listening socket ### socktype ``` $socktype = $listener->socktype; ``` Returns the socket type of the underlying listening socket ### listen ``` await $listener->listen( %params ); ``` 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: - on\_listen =\> CODE 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 ); ``` ## 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 listen on 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", }, ... ); ``` ### Using A Kernel-Assigned Port Number Rather than picking a specific port number, is it possible to ask the kernel to assign one arbitrarily that is currently free. This can be done by requesting port number 0 (which is actually the default if no port number is otherwise specified). To determine which port number the kernel actually picked, inspect the `"sockport"` accessor on the actual socket filehandle. Either use the Future returned by the `"listen"` method: ``` $listener->listen( addr => { family => "inet" }, )->on_done( sub { my ( $listener ) = @_; my $socket = $listener->read_handle; say "Now listening on port ", $socket->sockport; }); ``` Or pass an `"on_listen"` continuation: ``` $listener->listen( addr => { family => "inet" }, on_listen => sub { my ( $listener ) = @_; my $socket = $listener->read_handle; say "Now listening on port ", $socket->sockport; }, ); ``` ## AUTHOR Paul Evans \