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        $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
25        $loop->resolve( type => 'getpwuid', data => [ $< ] )
26           ->on_done( sub {
27           print "My passwd ent: " . join( "|", @_ ) . "\n";
28        });
29
30        $loop->run;
31

DESCRIPTION

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
38       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
48       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

METHODS

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

FUNCTIONS

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
226       $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
230       $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

BUILT-IN RESOLVERS

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
243        getpwnam getpwuid
244        getgrnam getgrgid
245        getservbyname getservbyport
246        gethostbyname gethostbyaddr
247        getnetbyname getnetbyaddr
248        getprotobyname getprotobynumber
249
250       The following three resolver names are implemented using the Socket
251       module.
252
253        getaddrinfo
254        getaddrinfo_array
255        getnameinfo
256
257       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
265       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
272       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
278       The "getnameinfo" resolver returns its result in the same form as
279       "Socket".
280
281       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

EXAMPLES

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
294        @numbers = qw( zero  one   two   three four
295                       five  six   seven eight nine  );
296
297        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
303        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

AUTHOR

312       Paul Evans <leonerd@leonerd.org.uk>
313
314
315
316perl v5.30.1                      2020-01-30            IO::Async::Resolver(3)
Impressum