Net::DNS::Native - non-blocking system DNS resolver

       Oleg G, <oleg@cpan.org>

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself

perl v5.40.0                                       2024-10-20                              Net::DNS::Native(3pm)

       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.

       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.

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.

       Net::DNS::Native - non-blocking system DNS resolver

           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;