Provided by: libnet-dns-native-perl_0.22-2build5_amd64 
NAME
Net::DNS::Native - non-blocking system DNS resolver
SYNOPSIS
use Net::DNS::Native;
use IO::Select;
use Socket;
my $dns = Net::DNS::Native->new();
my $sock = $dns->getaddrinfo("google.com");
my $sel = IO::Select->new($sock);
$sel->can_read(); # wait until resolving done
my ($err, @res) = $dns->get_result($sock);
die "Resolving failed: ", $err if ($err);
for my $r (@res) {
warn "google.com has ip ",
$r->{family} == AF_INET ?
inet_ntoa((unpack_sockaddr_in($r->{addr}))[1]) : # IPv4
Socket::inet_ntop(AF_INET6, (unpack_sockaddr_in6($r->{addr}))[1]); # IPv6
}
use Net::DNS::Native;
use AnyEvent;
use Socket;
my $dns = Net::DNS::Native->new;
my $cv = AnyEvent->condvar;
$cv->begin;
for my $host ('google.com', 'google.ru', 'google.cy') {
my $fh = $dns->inet_aton($host);
$cv->begin;
my $w; $w = AnyEvent->io(
fh => $fh,
poll => 'r',
cb => sub {
my $ip = $dns->get_result($fh);
warn $host, $ip ? " has ip " . inet_ntoa($ip) : " has no ip";
$cv->end;
undef $w;
}
)
}
$cv->end;
$cv->recv;
DESCRIPTION
This class provides several methods for host name resolution. It is designed to be used with event loops.
All resolving are done by getaddrinfo(3) implemented in your system library. Since getaddrinfo() is
blocking function and we don't want to block, calls to this function will be done in separate thread.
This class uses system native threads and not perl threads. So overhead shouldn't be too big.
INSTALLATION WARNING
For some platforms to support threaded extensions like this one your perl should be linked with threads
library. At the installation time this module will check is your perl is good enough and will not install
if not.
If it will fail to install use instructions listed below.
One of the possible solution to make your perl compatible with this module is to build perl with perl
threads support using "-Dusethreads" for "Configure" script. Other solution is to use "-A
prepend:libswanted="pthread "", which will just link non-threaded perl with pthreads. This is done by
default since Perl 5.22.
On Linux with perl not linked with pthreads this module may die with appropriate message at require time.
This may happen if you are called some functions from system library related to DNS operations before
loading of "Net::DNS::Native" (or some module, like "IO::Socket::IP", that you are already loaded, called
it internally). So, on such perl "use IO::Socket::IP; use Net::DNS::Native" may fail, but "use
Net::DNS::Native; use IO::Socket::IP" will success. The reason of such check inside "Net::DNS::Native" is
that calls to this functions (gethostbyname, getprotobyname, inet_aton, getaddrinfo, ...) will cause
loading of non-thread safe versions of DNS related stuff and "Net::DNS::Native" loaded after that will
not be able to override this with thread safe versions. So, at one moment your program will simply exit
with segfault. This is why this check and rule are very important.
METHODS
new
This is a class constructor. Accepts this optional parameters:
pool => $size
If $size>0 will create thread pool with size=$size which will make resolving job. Otherwise will use
default behavior: create and finish thread for each resolving request. If thread pool is not enough
big to process all supplied requests, than this requests will be queued until one of the threads will
become free to process next request from the queue.
extra_thread => $bool
If pool option specified and $bool has true value will create temporary extra thread for each request
that can't be handled by the pool (when all workers in the pool are busy) instead of pushing it to
the queue. This temporary thread will be finished immediatly after it will process request.
notify_on_begin => $bool
Extra mechanizm to notify caller that resolving for some host started. This is usefull for those who
uses thread pool without "extra_thread" option. When pool becomes full new queries will be queued, so
you can specify $bool with true value if you want to receive notifications when resolving will be
really started. To notify it will simply make $handle received by methods below readable. After that
you will need to read data from this handle to make it non readable again, so you can receive next
notification, when host resolving will be done. There will be 1 byte of data which you should read.
"1" for notification about start of the resolving and "2" for notification about finish of the
resolving.
my $dns = Net::DNS::Native->new(pool => 1, notify_on_begin => 1);
my $handle = $dns->inet_aton("google.com");
my $sel = IO::Select->new($handle);
$sel->can_read(); # wait "begin" notification
sysread($handle, my $buf, 1); # $buf eq "1", $handle is not readable again
$sel->can_read(); # wait "finish" notification
# resolving done
# we can sysread($handle, $buf, 1); again and $buf will be eq "2"
# but this is not necessarily
my $ip = $dns->get_result($handle);
getaddrinfo($host, $service, $hints)
This is the most powerfull method. May resolve host to both IPv4 and IPv6 addresses. For full
documentation see getaddrinfo(). This method accepts same parameters but instead of result returns
handle on which you need to wait for availability to read.
inet_pton($family, $host)
This method will resolve $host accordingly to $family, which may be AF_INET to resolve to IPv4 or
AF_INET6 to resolve to IPv6. For full documentation see inet_pton(). This method accepts same parameters
but instead of result returns handle on which you need to wait for availability to read.
inet_aton($host)
This method may be used only for resolving to IPv4. For full documentation see inet_aton(). This method
accepts same parameters but instead of result returns handle on which you need to wait for availability
to read.
gethostbyname($host)
This method may be used only for resolving to IPv4. For full documentation see gethostbyname(). This
method accepts same parameters but instead of result returns handle on which you need to wait for
availability to read.
get_result($handle)
After handle returned by methods above will became ready for read you should call this method with handle
as argument. It will return results appropriate to the method which returned this handle. For
"getaddrinfo" this will be "($err, @res)" list. For "inet_pton" and "inet_aton" $packed_address or
"undef". For gethostbyname() $packed_address or "undef" in scalar context and
"($name,$aliases,$addrtype,$length,@addrs)" in list context.
NOTE: it is important to call get_result() on returned handle when it will become ready for read. Because
this method destroys resources associated with this handle. Otherwise you will get memory leaks.
timedout($handle)
Mark resolving operation associated with this handle as timed out. This will not interrupt resolving
operation (because there is no way to interrupt getaddrinfo(3) correctly), but will automatically discard
any results returned when resolving will be done. So, after timedout($handle) you can forget about
$handle and associated resolving operation. And don't need to call get_result($handle) to destroy
resources associated with this handle. Furthermore, if you are using thread pool and all threads in pool
are busy and "extra_thread" option not specified, but 1 resolving operation from this pool marked as
timed out and you'll add one more resolving operation, this operation will not be queued. Instead of this
1 temporary extra thread will be created to process this operation. So you can think about "timedout"
like about real interrupter of long running resolving operation. But you are warned how it really works.
Note: since 0.16 handles will be automatically marked as timedout during destruction, so you no need more
to call timedout($handle) yourself, just lose last reference to this handle.
AUTHOR
Oleg G, <oleg@cpan.org>
COPYRIGHT AND LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself
perl v5.38.2 2024-03-31 Net::DNS::Native(3pm)