1POE::Component::ResolveUrs(e3r)Contributed Perl DocumentPaOtEi:o:nComponent::Resolver(3)
2
6 POE::Component::Resolver - A non-blocking getaddrinfo() resolver
7
9 version 0.921
10
12 #!/usr/bin/perl
13 use warnings;
15 use strict;
16 use POE;
18 use POE::Component::Resolver qw(AF_INET AF_INET6);
19 my $r = POE::Component::Resolver->new(
21 max_resolvers => 8,
22 idle_timeout => 5,
23 af_order => [ AF_INET6, AF_INET ],
24 # sidecar_program => $path_to_program,
25 );
26 my @hosts = qw( ipv6-test.com );
28 my $tcp = getprotobyname("tcp");
29 POE::Session->create(
31 inline_states => {
32 _start => sub {
33 foreach my $host (@hosts) {
34 $r->resolve(
35 host => $host,
36 service => "http",
37 event => "got_response",
38 hints => { protocol => $tcp },
39 ) or die $!;
40 }
41 },
42 _stop => sub { print "client session stopped\n" },
44 got_response => sub {
46 my ($error, $addresses, $request) = @_[ARG0..ARG2];
47 use YAML; print YAML::Dump(
48 {
49 error => $error,
50 addr => $addresses,
51 req => $request,
52 }
53 );
54 },
55 }
56 );
57 POE::Kernel->run();
59
61 POE::Component::Resolver performs Socket::getaddrinfo() calls in
62 subprocesses where they're permitted to block as long as necessary.
63 By default it will run eight subprocesses and prefer address families
65 in whatever order getaddrinfo() returns them. These defaults can be
66 overridden with constructor parameters. getaddrinfo() delegates to the
67 operating system's resolver, which may be reconfigured according to the
68 usual conventions.
69 PUBLIC METHODS
71 new
72 Create a new resolver. Returns an object that must be held and used to
74 make requests. See the synopsis.
75 Accepts up to four optional named parameters.
77 "af_order" may contain an arrayref with the address families to permit,
79 in the order in which they're preferred. Without "af_order", the
80 component will prefer IPv4 addresses over IPv6 for legacy
81 compatibility. This may change in the future as IPv6 gains more
82 widespread acceptance. See "ENVIRONMENT VARIABLES" for a way to
83 override the default without hacking modules.
84 # Prefer IPv6 addresses, but also return IPv4 ones.
86 my $r1 = POE::Component::Resolver->new(
87 af_order => [ AF_INET6, AF_INET ]
88 );
89 # Only return IPv6 addresses,
91 # or nothing in cases where only IPv4 addresses exist.
92 my $r2 = POE::Component::Resolver->new(
93 af_order => [ AF_INET6 ]
94 );
95 "idle_timeout" determines how long to keep idle resolver subprocesses
97 before cleaning them up, in seconds. It defaults to 15.0 seconds.
98 "max_resolvers" controls the component's parallelism by defining the
100 maximum number of sidecar processes to manage. It defaults to 8, but
101 fewer or more processes can be configured depending on the resources
102 you have available and the amount of parallelism you require.
103 # One at a time, but without the pesky blocking.
105 my $r3 = POE::Component::Resolver->new( max_resolvers => 1 );
106 "sidecar_program" contains the disk location of a program that will
108 perform blocking lookups on standard input and print the results on
109 standard output. The sidecar program is needed only in special
110 environments where the bundling and execution of extra utilities is
111 tricky. PAR is one such environment.
112 The sidecar program needs to contain at least two statements:
114 use POE::Component::Resolver::Sidecar;
116 POE::Component::Resover::Sidecar->main();
117 resolve
119 resolve() begins a new request to resolve a domain. The request will
121 be enqueued in the component until a sidecar process can service it.
122 resolve() returns a request ID that may be used to cancel() a request
123 before it has completed (or undef if the request couldn't begin, such
124 as during shutdown). Resolve requires two parameters and accepts some
125 additional optional ones.
126 "host" and "service" are required and contain the host (name or
128 Internet address) and service (name or numeric port) that will be
129 passed verbatim to getaddrinfo(). See Socket for details.
130 "event" is optional; it contains the name of the event that will
132 contain the resolver response. If omitted, it will default to
133 "resolver_response"; you may want to specify a shorter event name.
134 "hints" is optional. If specified, it must contain a hashref of hints
136 exactly as getaddrinfo() expects them. See Socket for details.
137 "misc" is optional continuation data that will be passed back in the
139 response. It may contain any type of data the application requires.
140 cancel
142 Cancel a request, given the request's ID.
144 my $request_id = $resolver->resolve("poe.dyndns.org", "http");
146 $resolver->cancel($request_id);
147 shutdown
149 Shut down the resolver. POE::Component::Resolver retains resources
151 including child processes for up to "idle_timeout" seconds. This may
152 keep programs running up to "idle_timeout" seconds longer than they
153 should.
154 POE::Component::Resolver will release its resources (including child
156 processes) when its shutdown() method is called.
157 unpack_addr
159 In scalar context, unpack_addr($response_addr_hashref) returns the addr
161 element of $response_addr_hashref in a numeric form appropriate for the
162 address family of the address.
163 sub handle_resolver_response {
165 my ($error, $addresses, $request) = @_[ARG0..ARG2];
166 foreach my $a (@$addresses) {
168 my $numeric_addr = $resolver->unpack_addr($a);
169 print "$request->{host} = $numeric_addr\n";
170 }
171 }
172 In list context, it returns the numeric port and address.
174 sub handle_resolver_response {
176 my ($error, $addresses, $request) = @_[ARG0..ARG2];
177 foreach my $a (@$addresses) {
179 my ($$numeric_addr, $port) = $resolver->unpack_addr($a);
180 print "$request->{host} = $numeric_addr\n";
181 }
182 }
183 unpack_addr() is a convenience wrapper around getnameinfo() from
185 Socket. You're certainly welcome to use the discrete function instead.
186 unpack_addr() returns bleak emptiness on failure, regardless of
188 context. You can check for undef return.
189 PUBLIC EVENTS
191 resolver_response
192 The resolver response event includes three parameters.
194 $_[ARG0] and $_[ARG1] contain the retrn values from Socket's
196 getaddrinfo() call. These are an error message (if the call failed),
197 and an arrayref of address structures if the call succeeded.
198 The component provides its own error message, 'component shut down'.
200 This response is given for every pending request at the time the user
201 shuts down the component.
202 $_[ARG2] contains a hashref of information provided to the resolve()
204 method. Specifically, the values of resolve()'s "host", "service" and
205 "misc" parameters.
206
208 POCO_RESOLVER_IPV
209 The POCO_RESOLVER_IPV environment variable sets this component's
210 default Internet Protocol Version search order. If the variable
211 exists, it should contain a string with the numbers 4 and/or 6.
212 POE::Component::Resolver will treate these as Internet Protocol
213 versions to consider, in the order they are preferred.
214 POE::Component::Resolver's new() method accepts an "af_order" parameter
216 that overrides this environment variable.
217 Default to IPv4 addresses only:
219 export POCO_RESOLVER_IPV=4
221 Default to IPv6 addresses only:
223 export POCO_RESOLVER_IPV=6
225 Prefer IPv6, but accept IPv4 if needed:
227 export POCO_RESOLVER_IPV=64
229 Prefer IPv4, but accept IPv6 if needed:
231 export POCO_RESOLVER_IPV=46
233
235 Microsoft Windows
236 This module requires "Microsoft TCP/IP version 6" to be installed.
237 Steps for Windows XP Pro (the steps for your particular version of
238 Windows may be subtly or drastically different):
239 • Open your Control Panel
241 • Open your Network Connections
243 • Select your network connection from the available one(s)
245 • In the Local Area Connection Status dialog, click the Properties
247 button
248 • If "Microsoft TCP/IP version 6" is listed as an item being used,
250 you are done.
251 • Otherwise click Install...
253 • Choose to add a Protocol
255 • And install "Microsoft TCP/IP version 6" from the list of network
257 protocols.
258
260 There is no timeout on requests.
261 There is no way to cancel a pending request.
263
265 programs linger for several seconds before exiting
266 Programs should shutdown() their POE::Component::Resolver objects when
267 they are through needing asynchronous DNS resolution. Programs should
268 additionally destroy their resolvers if they intend to run awhile and
269 want to reuse the memory they consume.
270 In some cases, it may be necessary to shutdown components that perform
272 asynchronous DNS using POE::Component::Resolver... such as
273 POE::Component::IRC, POE::Component::Client::Keepalive and
274 POE::Component::Client::HTTP.
275 By default, the resolver subprocesses hang around for idle_timeout,
277 which defaults to 15.0 seconds. Destroying the Resolver object will
278 clean up the process pool. Assuming only that is keeping the event
279 loop active, the program will then exit cleanly.
280 Alternatively, reduce idle_timeout to a more manageable number, such as
282 5.0 seconds.
283 Otherwise something else may also be keeping the event loop active.
285
287 Except where otherwise noted, this distribution is Copyright 2011 by
288 Rocco Caputo. All rights reserved. This distribution is free
289 software; you may redistribute it and/or modify it under the same terms
290 as Perl itself.
291perl v5.36.0 2023-01-20 POE::Component::Resolver(3)