1IO::Async::Listener(3)User Contributed Perl DocumentationIO::Async::Listener(3)
2
6 "IO::Async::Listener" - listen on network sockets for incoming
7 connections
8
10 use IO::Async::Listener;
11 use IO::Async::Loop;
13 my $loop = IO::Async::Loop->new;
14 my $listener = IO::Async::Listener->new(
16 on_stream => sub {
17 my ( undef, $stream ) = @_;
18 $stream->configure(
20 on_read => sub {
21 my ( $self, $buffref, $eof ) = @_;
22 $self->write( $$buffref );
23 $$buffref = "";
24 return 0;
25 },
26 );
27 $loop->add( $stream );
29 },
30 );
31 $loop->add( $listener );
33 $listener->listen(
35 service => "echo",
36 socktype => 'stream',
37 )->get;
38 $loop->run;
40 This object can also be used indirectly via an IO::Async::Loop:
42 use IO::Async::Stream;
44 use IO::Async::Loop;
46 my $loop = IO::Async::Loop->new;
47 $loop->listen(
49 service => "echo",
50 socktype => 'stream',
51 on_stream => sub {
53 ...
54 },
55 )->get;
56 $loop->run;
58
60 This subclass of IO::Async::Handle adds behaviour which watches a
61 socket in listening mode, to accept incoming connections on them.
62 A Listener can be constructed and given a existing socket in listening
64 mode. Alternatively, the Listener can construct a socket by calling
65 the "listen" method. Either a list of addresses can be provided, or a
66 service name can be looked up using the underlying loop's "resolve"
67 method.
68
70 The following events are invoked, either using subclass methods or CODE
71 references in parameters:
72 on_accept $clientsocket | $handle
74 Invoked whenever a new client connects to the socket.
75 If neither "handle_constructor" nor "handle_class" parameters are set,
77 this will be invoked with the new client socket directly. If a handle
78 constructor or class are set, this will be invoked with the newly-
79 constructed handle, having the new socket already configured onto it.
80 on_stream $stream
82 An alternative to "on_accept", this is passed an instance of
83 IO::Async::Stream when a new client connects. This is provided as a
84 convenience for the common case that a Stream object is required as the
85 transport for a Protocol object.
86 This is now vaguely deprecated in favour of using "on_accept" with a
88 handle constructor or class.
89 on_socket $socket
91 Similar to "on_stream", but constructs an instance of
92 IO::Async::Socket. This is most useful for "SOCK_DGRAM" or "SOCK_RAW"
93 sockets.
94 This is now vaguely deprecated in favour of using "on_accept" with a
96 handle constructor or class.
97 on_accept_error $socket, $errno
99 Optional. Invoked if the "accept" syscall indicates an error (other
100 than "EAGAIN" or "EWOULDBLOCK"). If not provided, failures of "accept"
101 will be passed to the main "on_error" handler.
102
104 The following named parameters may be passed to "new" or "configure":
105 on_accept => CODE
107 on_stream => CODE
108 on_socket => CODE
109 CODE reference for the event handlers. Because of the mutually-
110 exclusive nature of their behaviour, only one of these may be set at a
111 time. Setting one will remove the other two.
112 handle => IO
114 The IO handle containing an existing listen-mode socket.
115 handle_constructor => CODE
117 Optional. If defined, gives a CODE reference to be invoked every time a
118 new client socket is accepted from the listening socket. It is passed
119 the listener object itself, and is expected to return a new instance of
120 IO::Async::Handle or a subclass, used to wrap the new client socket.
121 $handle = $handle_constructor->( $listener )
123 This can also be given as a subclass method
125 $handle = $listener->handle_constructor()
127 handle_class => STRING
129 Optional. If defined and "handle_constructor" isn't, then new wrapper
130 handles are constructed by invoking the "new" method on the given class
131 name, passing in no additional parameters.
132 $handle = $handle_class->new()
134 This can also be given as a subclass method
136 $handle = $listener->handle_class->new
138 acceptor => STRING|CODE
140 Optional. If defined, gives the name of a method or a CODE reference to
141 use to implement the actual accept behaviour. This will be invoked as:
142 ( $accepted ) = $listener->acceptor( $socket )->get
144 ( $handle ) = $listener->acceptor( $socket, handle => $handle )->get
146 It is invoked with the listening socket as its its argument, and
148 optionally an IO::Async::Handle instance as a named parameter, and is
149 expected to return a "Future" that will eventually yield the newly-
150 accepted socket or handle instance, if such was provided.
151
153 The following methods documented with a trailing call to "->get" return
154 Future instances.
155 acceptor
157 $acceptor = $listener->acceptor
158 Returns the currently-set "acceptor" method name or code reference.
160 This may be of interest to Loop "listen" extension methods that wish to
161 extend or wrap it.
162 sockname
164 $name = $listener->sockname
165 Returns the "sockname" of the underlying listening socket
167 family
169 $family = $listener->family
170 Returns the socket address family of the underlying listening socket
172 socktype
174 $socktype = $listener->socktype
175 Returns the socket type of the underlying listening socket
177 listen
179 $listener->listen( %params )->get
180 This method sets up a listening socket and arranges for the acceptor
182 callback to be invoked each time a new connection is accepted on the
183 socket.
184 Most parameters given to this method are passed into the "listen"
186 method of the IO::Async::Loop object. In addition, the following
187 arguments are also recognised directly:
188 on_listen => CODE
190 Optional. A callback that is invoked when the listening socket
191 is ready. Similar to that on the underlying loop method,
192 except it is passed the listener object itself.
193 $on_listen->( $listener )
195
197 Listening on UNIX Sockets
198 The "handle" argument can be passed an existing socket already in
199 listening mode, making it possible to listen on other types of socket
200 such as UNIX sockets.
201 use IO::Async::Listener;
203 use IO::Socket::UNIX;
204 use IO::Async::Loop;
206 my $loop = IO::Async::Loop->new;
207 my $listener = IO::Async::Listener->new(
209 on_stream => sub {
210 my ( undef, $stream ) = @_;
211 $stream->configure(
213 on_read => sub {
214 my ( $self, $buffref, $eof ) = @_;
215 $self->write( $$buffref );
216 $$buffref = "";
217 return 0;
218 },
219 );
220 $loop->add( $stream );
222 },
223 );
224 $loop->add( $listener );
226 my $socket = IO::Socket::UNIX->new(
228 Local => "echo.sock",
229 Listen => 1,
230 ) or die "Cannot make UNIX socket - $!\n";
231 $listener->listen(
233 handle => $socket,
234 );
235 $loop->run;
237 Passing Plain Socket Addresses
239 The "addr" or "addrs" parameters should contain a definition of a plain
240 socket address in a form that the IO::Async::OS "extract_addrinfo"
241 method can use.
242 This example shows how to listen on TCP port 8001 on address 10.0.0.1:
244 $listener->listen(
246 addr => {
247 family => "inet",
248 socktype => "stream",
249 port => 8001,
250 ip => "10.0.0.1",
251 },
252 ...
253 );
254 This example shows another way to listen on a UNIX socket, similar to
256 the earlier example:
257 $listener->listen(
259 addr => {
260 family => "unix",
261 socktype => "stream",
262 path => "echo.sock",
263 },
264 ...
265 );
266 Using A Kernel-Assigned Port Number
268 Rather than picking a specific port number, is it possible to ask the
269 kernel to assign one arbitrarily that is currently free. This can be
270 done by requesting port number 0 (which is actually the default if no
271 port number is otherwise specified). To determine which port number the
272 kernel actually picked, inspect the "sockport" accessor on the actual
273 socket filehandle.
274 Either use the Future returned by the "listen" method:
276 $listener->listen(
278 addr => { family => "inet" },
279 )->on_done( sub {
280 my ( $listener ) = @_;
281 my $socket = $listener->read_handle;
282 say "Now listening on port ", $socket->sockport;
284 });
285 Or pass an "on_listen" continuation:
287 $listener->listen(
289 addr => { family => "inet" },
290 on_listen => sub {
292 my ( $listener ) = @_;
293 my $socket = $listener->read_handle;
294 say "Now listening on port ", $socket->sockport;
296 },
297 );
298
300 Paul Evans <leonerd@leonerd.org.uk>
301perl v5.36.0 2023-01-20 IO::Async::Listener(3)