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::Stream;
12 use IO::Async::Loop;
14 my $loop = IO::Async::Loop->new();
15 my $listener = IO::Async::Listener->new(
17 on_accept => sub {
18 my ( $newclient ) = @_;
19 $loop->add( IO::Async::Stream->new(
21 handle => $newclient,
22 on_read => sub {
24 my ( $self, $buffref, $closed ) = @_;
25 $self->write( $$buffref );
26 $$buffref = "";
27 return 0;
28 },
29 ) );
30 },
31 );
32 $loop->add( $listener );
34 $listener->listen(
36 service => "echo",
37 socktype => 'stream',
38 on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
40 on_listen_error => sub { print STDERR "Cannot listen\n"; },
41 );
42 $loop->loop_forever;
44 This object can also be used indirectly via an "IO::Async::Loop":
46 use IO::Async::Stream;
48 use IO::Async::Loop;
50 my $loop = IO::Async::Loop->new();
51 $loop->listen(
53 service => "echo",
54 socktype => 'stream',
55 on_accept => sub {
57 ...
58 },
59 on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
61 on_listen_error => sub { print STDERR "Cannot listen\n"; },
62 );
63 $loop->loop_forever;
65
67 This subclass of IO::Async::Handle adds behaviour which watches a
68 socket in listening mode, to accept incoming connections on them.
69 A Listener can be constructed and given a existing socket in listening
71 mode. Alternatively, the Listener can construct a socket by calling
72 the "listen" method. Either a list of addresses can be provided, or a
73 service name can be looked up using the underlying loop's "resolve"
74 method.
75 This object may be used in one of two ways; with a callback function,
77 or as a base class.
78 Callbacks
80 If the "on_accept" key is supplied to the constructor, it should
81 contain a CODE reference to a callback function to be invoked when
82 a new client connects to the socket. It is passed an "IO::Socket"
83 reference to the newly accepted socket:
84 $on_accept->( $self, $clientsocket )
86 Base Class
88 If a subclass is built, then it can override the "on_accept"
89 method.
90 $self->on_accept( $clientsocket )
92
94 The following named parameters may be passed to "new" or "configure":
95 on_accept => CODE
97 A callback that is invoked whenever a new client connects to
98 the socket. If not supplied the subclass method will be called
99 instead.
100 handle => IO
102 The IO handle containing an existing listen-mode socket.
103
105 $listener->listen( %params )
106 This method sets up a listening socket using the addresses given, and
107 will invoke the "on_accept" callback each time a new connection is
108 accepted on the socket. Addresses may be given directly, or they may be
109 looked up using the system's name resolver.
110 If multiple addresses are given, or resolved from the service and
112 hostname, then each will be attempted in turn until one succeeds.
113 In plain address mode, the %params hash takes the following keys:
115 addrs => ARRAY
117 Reference to an array of (possibly-multiple) address structures
118 to attempt to listen on. Each should be in the layout described
119 for "addr". Such a layout is returned by the "getaddrinfo"
120 named resolver.
121 addr => ARRAY
123 Shortcut for passing a single address to listen on; it may be
124 passed directly with this key, instead of in another array of
125 its own.
126 The address (or each element of the "addrs" array) should be a
128 reference to an array, with at least the following elements:
129 [ $family, $socktype, $protocol, $address ]
131 The first three arguments will be passed to a "socket()" call
133 and, if successful, the fourth to a "bind()" call on the
134 resulting socket. The socket will then be "listen()"ed to put
135 it into listening mode. Any trailing elements in this array
136 will be ignored.
137 In named resolver mode, the %params hash takes the following keys:
139 service => STRING
141 The service name to listen on.
142 host => STRING
144 The hostname to listen on. Optional. Will listen on all
145 addresses if not supplied.
146 family => INT
148 socktype => INT
149 protocol => INT
150 flags => INT
151 Optional. Other arguments to pass along with "host" and
152 "service" to the "getaddrinfo()" call.
153 socktype => STRING
155 Optionally may instead be one of the values 'stream', 'dgram'
156 or 'raw' to stand for "SOCK_STREAM", "SOCK_DGRAM" or
157 "SOCK_RAW". This utility is provided to allow the caller to
158 avoid a separate "use Socket" only for importing these
159 constants.
160 on_resolve_error => CODE
162 A continuation that is invoked when the name resolution attempt
163 fails. This is invoked in the same way as the "on_error"
164 continuation for the "resolve" method.
165 In either case, the following keys are also taken:
167 on_listen => CODE
169 Optional. A callback that is invoked when the listening socket
170 is ready.
171 $on_listen->( $listener )
173 on_listen_error => CODE
175 A continuation this is invoked after all of the addresses have
176 been tried, and none of them succeeded. Becasue there is no one
177 error message that stands out as particularly noteworthy, none
178 is given to this continuation. To track individual errors, see
179 the "on_fail" callback.
180 on_fail => CODE
182 Optional. A callback that is invoked if a syscall fails while
183 attempting to create a listening sockets. It is passed the name
184 of the syscall that failed, the arguments that were passed to
185 it, and the error generated. I.e.
186 $on_fail->( "socket", $family, $socktype, $protocol, $! );
188 $on_fail->( "sockopt", $sock, $optname, $optval, $! );
190 $on_fail->( "bind", $sock, $address, $! );
192 $on_fail->( "listen", $sock, $queuesize, $! );
194 queuesize => INT
196 Optional. The queue size to pass to the "listen()" calls. If
197 not supplied, then 3 will be given instead.
198 reuseaddr => BOOL
200 Optional. If true or not supplied then the "SO_REUSEADDR"
201 socket option will be set. To prevent this, pass a false value
202 such as 0.
203
205 Paul Evans <leonerd@leonerd.org.uk>
206perl v5.12.1 2010-06-09 IO::Async::Listener(3)