1IO::Async::Listener(3)User Contributed Perl DocumentationIO::Async::Listener(3)
2
3
4

NAME

6       "IO::Async::Listener" - listen on network sockets for incoming
7       connections
8

SYNOPSIS

10          use IO::Async::Listener;
11
12          use IO::Async::Loop;
13          my $loop = IO::Async::Loop->new;
14
15          my $listener = IO::Async::Listener->new(
16             on_stream => sub {
17                my ( undef, $stream ) = @_;
18
19                $stream->configure(
20                   on_read => sub {
21                      my ( $self, $buffref, $eof ) = @_;
22                      $self->write( $$buffref );
23                      $$buffref = "";
24                      return 0;
25                   },
26                );
27
28                $loop->add( $stream );
29             },
30          );
31
32          $loop->add( $listener );
33
34          $listener->listen(
35             service  => "echo",
36             socktype => 'stream',
37          )->get;
38
39          $loop->run;
40
41       This object can also be used indirectly via an IO::Async::Loop:
42
43          use IO::Async::Stream;
44
45          use IO::Async::Loop;
46          my $loop = IO::Async::Loop->new;
47
48          $loop->listen(
49             service  => "echo",
50             socktype => 'stream',
51
52             on_stream => sub {
53                ...
54             },
55          )->get;
56
57          $loop->run;
58

DESCRIPTION

60       This subclass of IO::Async::Handle adds behaviour which watches a
61       socket in listening mode, to accept incoming connections on them.
62
63       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

EVENTS

70       The following events are invoked, either using subclass methods or CODE
71       references in parameters:
72
73   on_accept $clientsocket | $handle
74       Invoked whenever a new client connects to the socket.
75
76       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
81   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
87       This is now vaguely deprecated in favour of using "on_accept" with a
88       handle constructor or class.
89
90   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
95       This is now vaguely deprecated in favour of using "on_accept" with a
96       handle constructor or class.
97
98   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

PARAMETERS

104       The following named parameters may be passed to "new" or "configure":
105
106   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
113   handle => IO
114       The IO handle containing an existing listen-mode socket.
115
116   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
122          $handle = $handle_constructor->( $listener )
123
124       This can also be given as a subclass method
125
126          $handle = $listener->handle_constructor()
127
128   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
133          $handle = $handle_class->new()
134
135       This can also be given as a subclass method
136
137          $handle = $listener->handle_class->new
138
139   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
143          ( $accepted ) = $listener->acceptor( $socket )->get
144
145          ( $handle ) = $listener->acceptor( $socket, handle => $handle )->get
146
147       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

METHODS

153       The following methods documented with a trailing call to "->get" return
154       Future instances.
155
156   acceptor
157          $acceptor = $listener->acceptor
158
159       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
163   sockname
164          $name = $listener->sockname
165
166       Returns the "sockname" of the underlying listening socket
167
168   family
169          $family = $listener->family
170
171       Returns the socket address family of the underlying listening socket
172
173   socktype
174          $socktype = $listener->socktype
175
176       Returns the socket type of the underlying listening socket
177
178   listen
179          $listener->listen( %params )->get
180
181       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
185       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
189       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
194                  $on_listen->( $listener )
195

EXAMPLES

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
202          use IO::Async::Listener;
203          use IO::Socket::UNIX;
204
205          use IO::Async::Loop;
206          my $loop = IO::Async::Loop->new;
207
208          my $listener = IO::Async::Listener->new(
209             on_stream => sub {
210                my ( undef, $stream ) = @_;
211
212                $stream->configure(
213                   on_read => sub {
214                      my ( $self, $buffref, $eof ) = @_;
215                      $self->write( $$buffref );
216                      $$buffref = "";
217                      return 0;
218                   },
219                );
220
221                $loop->add( $stream );
222             },
223          );
224
225          $loop->add( $listener );
226
227          my $socket = IO::Socket::UNIX->new(
228             Local => "echo.sock",
229             Listen => 1,
230          ) or die "Cannot make UNIX socket - $!\n";
231
232          $listener->listen(
233             handle => $socket,
234          );
235
236          $loop->run;
237
238   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
243       This example shows how to listen on TCP port 8001 on address 10.0.0.1:
244
245          $listener->listen(
246             addr => {
247                family   => "inet",
248                socktype => "stream",
249                port     => 8001,
250                ip       => "10.0.0.1",
251             },
252             ...
253          );
254
255       This example shows another way to listen on a UNIX socket, similar to
256       the earlier example:
257
258          $listener->listen(
259             addr => {
260                family   => "unix",
261                socktype => "stream",
262                path     => "echo.sock",
263             },
264             ...
265          );
266
267   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
275       Either use the Future returned by the "listen" method:
276
277          $listener->listen(
278             addr => { family => "inet" },
279          )->on_done( sub {
280             my ( $listener ) = @_;
281             my $socket = $listener->read_handle;
282
283             say "Now listening on port ", $socket->sockport;
284          });
285
286       Or pass an "on_listen" continuation:
287
288          $listener->listen(
289             addr => { family => "inet" },
290
291             on_listen => sub {
292                my ( $listener ) = @_;
293                my $socket = $listener->read_handle;
294
295                say "Now listening on port ", $socket->sockport;
296             },
297          );
298

AUTHOR

300       Paul Evans <leonerd@leonerd.org.uk>
301
302
303
304perl v5.36.0                      2022-05-31            IO::Async::Listener(3)
Impressum