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