Debian Codegraph @

README

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