1IO::Async::Resolver(3)User Contributed Perl DocumentationIO::Async::Resolver(3)
2
6 "IO::Async::Resolver" - performing name resolutions asynchronously
7
9 This object is used indirectly via an IO::Async::Loop:
10 use IO::Async::Loop;
12 my $loop = IO::Async::Loop->new;
13 $loop->resolver->getaddrinfo(
15 host => "www.example.com",
16 service => "http",
17 )->on_done( sub {
18 foreach my $addr ( @_ ) {
19 printf "http://www.example.com can be reached at " .
20 "socket(%d,%d,%d) + connect('%v02x')\n",
21 @{$addr}{qw( family socktype protocol addr )};
22 }
23 });
24 $loop->resolve( type => 'getpwuid', data => [ $< ] )
26 ->on_done( sub {
27 print "My passwd ent: " . join( "|", @_ ) . "\n";
28 });
29 $loop->run;
31
33 This module extends an IO::Async::Loop to use the system's name
34 resolver functions asynchronously. It provides a number of named
35 resolvers, each one providing an asynchronous wrapper around a single
36 resolver function.
37 Because the system may not provide asynchronous versions of its
39 resolver functions, this class is implemented using a
40 IO::Async::Function object that wraps the normal (blocking) functions.
41 In this case, name resolutions will be performed asynchronously from
42 the rest of the program, but will likely be done by a single background
43 worker process, so will be processed in the order they were requested;
44 a single slow lookup will hold up the queue of other requests behind
45 it. To mitigate this, multiple worker processes can be used; see the
46 "workers" argument to the constructor.
47 The "idle_timeout" parameter for the underlying IO::Async::Function
49 object is set to a default of 30 seconds, and "min_workers" is set to
50 0. This ensures that there are no spare processes sitting idle during
51 the common case of no outstanding requests.
52
54 The following methods documented with a trailing call to "->get" return
55 Future instances.
56 resolve
58 @result = $loop->resolve( %params )->get
59 Performs a single name resolution operation, as given by the keys in
61 the hash.
62 The %params hash keys the following keys:
64 type => STRING
66 Name of the resolution operation to perform. See BUILT-IN
67 RESOLVERS for the list of available operations.
68 data => ARRAY
70 Arguments to pass to the resolver function. Exact meaning
71 depends on the specific function chosen by the "type"; see
72 BUILT-IN RESOLVERS.
73 timeout => NUMBER
75 Optional. Timeout in seconds, after which the resolver
76 operation will abort with a timeout exception. If not supplied,
77 a default of 10 seconds will apply.
78 On failure, the fail category name is "resolve"; the details give the
80 individual resolver function name (e.g. "getaddrinfo"), followed by
81 other error details specific to the resolver in question.
82 ->fail( $message, resolve => $type => @details )
84 resolve (void)
86 $resolver->resolve( %params )
87 When not returning a future, additional parameters can be given
89 containing the continuations to invoke on success or failure:
90 on_resolved => CODE
92 A continuation that is invoked when the resolver function
93 returns a successful result. It will be passed the array
94 returned by the resolver function.
95 $on_resolved->( @result )
97 on_error => CODE
99 A continuation that is invoked when the resolver function
100 fails. It will be passed the exception thrown by the function.
101 getaddrinfo
103 @addrs = $resolver->getaddrinfo( %args )->get
104 A shortcut wrapper around the "getaddrinfo" resolver, taking its
106 arguments in a more convenient form.
107 host => STRING
109 service => STRING
110 The host and service names to look up. At least one must be
111 provided.
112 family => INT or STRING
114 socktype => INT or STRING
115 protocol => INT
116 Hint values used to filter the results.
117 flags => INT
119 Flags to control the getaddrinfo(3) function. See the "AI_*"
120 constants in Socket's "getaddrinfo" function for more detail.
121 passive => BOOL
123 If true, sets the "AI_PASSIVE" flag. This is provided as a
124 convenience to avoid the caller from having to import the
125 "AI_PASSIVE" constant from "Socket".
126 timeout => NUMBER
128 Time in seconds after which to abort the lookup with a "Timed
129 out" exception
130 On success, the future will yield the result as a list of HASH
132 references; each containing one result. Each result will contain fields
133 called "family", "socktype", "protocol" and "addr". If requested by
134 "AI_CANONNAME" then the "canonname" field will also be present.
135 On failure, the detail field will give the error number, which should
137 match one of the "Socket::EAI_*" constants.
138 ->fail( $message, resolve => getaddrinfo => $eai_errno )
140 As a specific optimisation, this method will try to perform a lookup of
142 numeric values synchronously, rather than asynchronously, if it looks
143 likely to succeed.
144 Specifically, if the service name is entirely numeric, and the hostname
146 looks like an IPv4 or IPv6 string, a synchronous lookup will first be
147 performed using the "AI_NUMERICHOST" flag. If this gives an
148 "EAI_NONAME" error, then the lookup is performed asynchronously
149 instead.
150 getaddrinfo (void)
152 $resolver->getaddrinfo( %args )
153 When not returning a future, additional parameters can be given
155 containing the continuations to invoke on success or failure:
156 on_resolved => CODE
158 Callback which is invoked after a successful lookup.
159 $on_resolved->( @addrs )
161 on_error => CODE
163 Callback which is invoked after a failed lookup, including for
164 a timeout.
165 $on_error->( $exception )
167 getnameinfo
169 ( $host, $service ) = $resolver->getnameinfo( %args )->get
170 A shortcut wrapper around the "getnameinfo" resolver, taking its
172 arguments in a more convenient form.
173 addr => STRING
175 The packed socket address to look up.
176 flags => INT
178 Flags to control the getnameinfo(3) function. See the "NI_*"
179 constants in Socket's "getnameinfo" for more detail.
180 numerichost => BOOL
182 numericserv => BOOL
183 dgram => BOOL
184 If true, set the "NI_NUMERICHOST", "NI_NUMERICSERV" or
185 "NI_DGRAM" flags.
186 numeric => BOOL
188 If true, sets both "NI_NUMERICHOST" and "NI_NUMERICSERV" flags.
189 timeout => NUMBER
191 Time in seconds after which to abort the lookup with a "Timed
192 out" exception
193 On failure, the detail field will give the error number, which should
195 match one of the "Socket::EAI_*" constants.
196 ->fail( $message, resolve => getnameinfo => $eai_errno )
198 As a specific optimisation, this method will try to perform a lookup of
200 numeric values synchronously, rather than asynchronously, if both the
201 "NI_NUMERICHOST" and "NI_NUMERICSERV" flags are given.
202 getnameinfo (void)
204 $resolver->getnameinfo( %args )
205 When not returning a future, additional parameters can be given
207 containing the continuations to invoke on success or failure:
208 on_resolved => CODE
210 Callback which is invoked after a successful lookup.
211 $on_resolved->( $host, $service )
213 on_error => CODE
215 Callback which is invoked after a failed lookup, including for
216 a timeout.
217 $on_error->( $exception )
219
221 register_resolver( $name, $code )
222 Registers a new named resolver function that can be called by the
223 "resolve" method. All named resolvers must be registered before the
224 object is constructed.
225 $name The name of the resolver function; must be a plain string. This
227 name will be used by the "type" argument to the "resolve"
228 method, to identify it.
229 $code A CODE reference to the resolver function body. It will be
231 called in list context, being passed the list of arguments
232 given in the "data" argument to the "resolve" method. The
233 returned list will be passed to the "on_resolved" callback. If
234 the code throws an exception at call time, it will be passed to
235 the "on_error" continuation. If it returns normally, the list
236 of values it returns will be passed to "on_resolved".
237
239 The following resolver names are implemented by the same-named perl
240 function, taking and returning a list of values exactly as the perl
241 function does:
242 getpwnam getpwuid
244 getgrnam getgrgid
245 getservbyname getservbyport
246 gethostbyname gethostbyaddr
247 getnetbyname getnetbyaddr
248 getprotobyname getprotobynumber
249 The following three resolver names are implemented using the Socket
251 module.
252 getaddrinfo
254 getaddrinfo_array
255 getnameinfo
256 The "getaddrinfo" resolver takes arguments in a hash of name/value
258 pairs and returns a list of hash structures, as the
259 "Socket::getaddrinfo" function does. For neatness it takes all its
260 arguments as named values; taking the host and service names from
261 arguments called "host" and "service" respectively; all the remaining
262 arguments are passed into the hints hash. This name is also aliased as
263 simply "getaddrinfo".
264 The "getaddrinfo_array" resolver behaves more like the "Socket6"
266 version of the function. It takes hints in a flat list, and mangles the
267 result of the function, so that the returned value is more useful to
268 the caller. It splits up the list of 5-tuples into a list of ARRAY
269 refs, where each referenced array contains one of the tuples of 5
270 values.
271 As an extra convenience to the caller, both resolvers will also accept
273 plain string names for the "family" argument, converting "inet" and
274 possibly "inet6" into the appropriate "AF_*" value, and for the
275 "socktype" argument, converting "stream", "dgram" or "raw" into the
276 appropriate "SOCK_*" value.
277 The "getnameinfo" resolver returns its result in the same form as
279 "Socket".
280 Because this module simply uses the system's "getaddrinfo" resolver, it
282 will be fully IPv6-aware if the underlying platform's resolver is. This
283 allows programs to be fully IPv6-capable.
284
286 The following somewhat contrieved example shows how to implement a new
287 resolver function. This example just uses in-memory data, but a real
288 function would likely make calls to OS functions to provide an answer.
289 In traditional Unix style, a pair of functions are provided that each
290 look up the entity by either type of key, where both functions return
291 the same type of list. This is purely a convention, and is in no way
292 required or enforced by the IO::Async::Resolver itself.
293 @numbers = qw( zero one two three four
295 five six seven eight nine );
296 register_resolver getnumberbyindex => sub {
298 my ( $index ) = @_;
299 die "Bad index $index" unless $index >= 0 and $index < @numbers;
300 return ( $index, $numbers[$index] );
301 };
302 register_resolver getnumberbyname => sub {
304 my ( $name ) = @_;
305 foreach my $index ( 0 .. $#numbers ) {
306 return ( $index, $name ) if $numbers[$index] eq $name;
307 }
308 die "Bad name $name";
309 };
310
312 Paul Evans <leonerd@leonerd.org.uk>
313perl v5.30.1 2020-01-30 IO::Async::Resolver(3)