1POE::Component::ResolveUrs(e3r)Contributed Perl DocumentPaOtEi:o:nComponent::Resolver(3)
2
3
4

NAME

6       POE::Component::Resolver - A non-blocking getaddrinfo() resolver
7

VERSION

9       version 0.921
10

SYNOPSIS

12               #!/usr/bin/perl
13
14               use warnings;
15               use strict;
16
17               use POE;
18               use POE::Component::Resolver qw(AF_INET AF_INET6);
19
20               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
27               my @hosts = qw( ipv6-test.com );
28               my $tcp   = getprotobyname("tcp");
29
30               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
43                               _stop => sub { print "client session stopped\n" },
44
45                               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
58               POE::Kernel->run();
59

DESCRIPTION

61       POE::Component::Resolver performs Socket::getaddrinfo() calls in
62       subprocesses where they're permitted to block as long as necessary.
63
64       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
70   PUBLIC METHODS
71       new
72
73       Create a new resolver.  Returns an object that must be held and used to
74       make requests.  See the synopsis.
75
76       Accepts up to four optional named parameters.
77
78       "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
85               # Prefer IPv6 addresses, but also return IPv4 ones.
86               my $r1 = POE::Component::Resolver->new(
87                       af_order => [ AF_INET6, AF_INET ]
88               );
89
90               # 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
96       "idle_timeout" determines how long to keep idle resolver subprocesses
97       before cleaning them up, in seconds.  It defaults to 15.0 seconds.
98
99       "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
104               # One at a time, but without the pesky blocking.
105               my $r3 = POE::Component::Resolver->new( max_resolvers => 1 );
106
107       "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
113       The sidecar program needs to contain at least two statements:
114
115               use POE::Component::Resolver::Sidecar;
116               POE::Component::Resover::Sidecar->main();
117
118       resolve
119
120       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
127       "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
131       "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
135       "hints" is optional.  If specified, it must contain a hashref of hints
136       exactly as getaddrinfo() expects them.  See Socket for details.
137
138       "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
141       cancel
142
143       Cancel a request, given the request's ID.
144
145               my $request_id = $resolver->resolve("poe.dyndns.org", "http");
146               $resolver->cancel($request_id);
147
148       shutdown
149
150       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
155       POE::Component::Resolver will release its resources (including child
156       processes) when its shutdown() method is called.
157
158       unpack_addr
159
160       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
164               sub handle_resolver_response {
165                       my ($error, $addresses, $request) = @_[ARG0..ARG2];
166
167                       foreach my $a (@$addresses) {
168                               my $numeric_addr = $resolver->unpack_addr($a);
169                               print "$request->{host} = $numeric_addr\n";
170                       }
171               }
172
173       In list context, it returns the numeric port and address.
174
175               sub handle_resolver_response {
176                       my ($error, $addresses, $request) = @_[ARG0..ARG2];
177
178                       foreach my $a (@$addresses) {
179                               my ($$numeric_addr, $port) = $resolver->unpack_addr($a);
180                               print "$request->{host} = $numeric_addr\n";
181                       }
182               }
183
184       unpack_addr() is a convenience wrapper around getnameinfo() from
185       Socket.  You're certainly welcome to use the discrete function instead.
186
187       unpack_addr() returns bleak emptiness on failure, regardless of
188       context.  You can check for undef return.
189
190   PUBLIC EVENTS
191       resolver_response
192
193       The resolver response event includes three parameters.
194
195       $_[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
199       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
203       $_[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

ENVIRONMENT VARIABLES

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
215       POE::Component::Resolver's new() method accepts an "af_order" parameter
216       that overrides this environment variable.
217
218       Default to IPv4 addresses only:
219
220               export POCO_RESOLVER_IPV=4
221
222       Default to IPv6 addresses only:
223
224               export POCO_RESOLVER_IPV=6
225
226       Prefer IPv6, but accept IPv4 if needed:
227
228               export POCO_RESOLVER_IPV=64
229
230       Prefer IPv4, but accept IPv6 if needed:
231
232               export POCO_RESOLVER_IPV=46
233

COMPATIBILITY ISSUES

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
240       •   Open your Control Panel
241
242       •   Open your Network Connections
243
244       •   Select your network connection from the available one(s)
245
246       •   In the Local Area Connection Status dialog, click the Properties
247           button
248
249       •   If "Microsoft TCP/IP version 6" is listed as an item being used,
250           you are done.
251
252       •   Otherwise click Install...
253
254       •   Choose to add a Protocol
255
256       •   And install "Microsoft TCP/IP version 6" from the list of network
257           protocols.
258

BUGS

260       There is no timeout on requests.
261
262       There is no way to cancel a pending request.
263

TROUBLESHOOTING

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
271       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
276       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
281       Alternatively, reduce idle_timeout to a more manageable number, such as
282       5.0 seconds.
283
284       Otherwise something else may also be keeping the event loop active.
285

LICENSE

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.
291
292
293
294perl v5.36.0                      2023-01-20       POE::Component::Resolver(3)
Impressum