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