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

NAME

6       "IO::Async::Resolver" - performing name resolutions asynchronously
7

SYNOPSIS

9       This object is used indirectly via an IO::Async::Loop:
10
11          use IO::Async::Loop;
12          my $loop = IO::Async::Loop->new;
13
14          my @results = $loop->resolver->getaddrinfo(
15             host    => "www.example.com",
16             service => "http",
17          )->get;
18
19          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
25          my @pwent = $loop->resolve( type => 'getpwuid', data => [ $< ] )->get;
26
27          print "My passwd ent: " . join( "|", @pwent ) . "\n";
28

DESCRIPTION

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
35       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
45       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

METHODS

51       The following methods documented with a trailing call to "->get" return
52       Future instances.
53
54   resolve
55          @result = $loop->resolve( %params )->get
56
57       Performs a single name resolution operation, as given by the keys in
58       the hash.
59
60       The %params hash keys the following keys:
61
62       type => STRING
63               Name of the resolution operation to perform. See BUILT-IN
64               RESOLVERS for the list of available operations.
65
66       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
71       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
76       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
80          ->fail( $message, resolve => $type => @details )
81
82   resolve (void)
83          $resolver->resolve( %params )
84
85       When not returning a future, additional parameters can be given
86       containing the continuations to invoke on success or failure:
87
88       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
93                  $on_resolved->( @result )
94
95       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
99   getaddrinfo
100          @addrs = $resolver->getaddrinfo( %args )->get
101
102       A shortcut wrapper around the "getaddrinfo" resolver, taking its
103       arguments in a more convenient form.
104
105       host => STRING
106       service => STRING
107               The host and service names to look up. At least one must be
108               provided.
109
110       family => INT or STRING
111       socktype => INT or STRING
112       protocol => INT
113               Hint values used to filter the results.
114
115       flags => INT
116               Flags to control the getaddrinfo(3) function. See the "AI_*"
117               constants in Socket's "getaddrinfo" function for more detail.
118
119       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
124       timeout => NUMBER
125               Time in seconds after which to abort the lookup with a "Timed
126               out" exception
127
128       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
133       On failure, the detail field will give the error number, which should
134       match one of the "Socket::EAI_*" constants.
135
136          ->fail( $message, resolve => getaddrinfo => $eai_errno )
137
138       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
142       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
148   getaddrinfo (void)
149          $resolver->getaddrinfo( %args )
150
151       When not returning a future, additional parameters can be given
152       containing the continuations to invoke on success or failure:
153
154       on_resolved => CODE
155               Callback which is invoked after a successful lookup.
156
157                  $on_resolved->( @addrs )
158
159       on_error => CODE
160               Callback which is invoked after a failed lookup, including for
161               a timeout.
162
163                  $on_error->( $exception )
164
165   getnameinfo
166          ( $host, $service ) = $resolver->getnameinfo( %args )->get
167
168       A shortcut wrapper around the "getnameinfo" resolver, taking its
169       arguments in a more convenient form.
170
171       addr => STRING
172               The packed socket address to look up.
173
174       flags => INT
175               Flags to control the getnameinfo(3) function. See the "NI_*"
176               constants in Socket's "getnameinfo" for more detail.
177
178       numerichost => BOOL
179       numericserv => BOOL
180       dgram => BOOL
181               If true, set the "NI_NUMERICHOST", "NI_NUMERICSERV" or
182               "NI_DGRAM" flags.
183
184       numeric => BOOL
185               If true, sets both "NI_NUMERICHOST" and "NI_NUMERICSERV" flags.
186
187       timeout => NUMBER
188               Time in seconds after which to abort the lookup with a "Timed
189               out" exception
190
191       On failure, the detail field will give the error number, which should
192       match one of the "Socket::EAI_*" constants.
193
194          ->fail( $message, resolve => getnameinfo => $eai_errno )
195
196       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
200   getnameinfo (void)
201          $resolver->getnameinfo( %args )
202
203       When not returning a future, additional parameters can be given
204       containing the continuations to invoke on success or failure:
205
206       on_resolved => CODE
207               Callback which is invoked after a successful lookup.
208
209                  $on_resolved->( $host, $service )
210
211       on_error => CODE
212               Callback which is invoked after a failed lookup, including for
213               a timeout.
214
215                  $on_error->( $exception )
216

FUNCTIONS

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
223       $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
227       $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

BUILT-IN RESOLVERS

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
240          getpwnam getpwuid
241          getgrnam getgrgid
242          getservbyname getservbyport
243          gethostbyname gethostbyaddr
244          getnetbyname getnetbyaddr
245          getprotobyname getprotobynumber
246
247       The following three resolver names are implemented using the Socket
248       module.
249
250          getaddrinfo
251          getaddrinfo_array
252          getnameinfo
253
254       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
262       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
269       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
275       The "getnameinfo" resolver returns its result in the same form as
276       "Socket".
277
278       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

EXAMPLES

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
291          @numbers = qw( zero  one   two   three four
292                         five  six   seven eight nine  );
293
294          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
300          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

AUTHOR

309       Paul Evans <leonerd@leonerd.org.uk>
310
311
312
313perl v5.36.0                      2022-05-31            IO::Async::Resolver(3)
Impressum