NAME

       Net::DNS::Async - Asynchronous DNS helper for high volume applications

SYNOPSIS

               use Net::DNS::Async;

               my $c = new Net::DNS::Async(QueueSize => 20, Retries => 3);

               for (...) {
                       $c->add(\&callback, @query);
               }
               $c->await();

               sub callback {
                       my $response = shift;
                       ...
               }

DESCRIPTION

       Net::DNS::Async is a fire-and-forget asynchronous DNS helper.  That is, the user application adds DNS
       questions to the helper, and the callback will be called at some point in the future without further
       intervention from the user application. The application need not handle selects, timeouts, waiting for a
       response or any other such issues.

       If the same query is added to the queue more than once, the module may combine the queries; that is, it
       will perform the query only once, and will call each callback registered for that query in turn, passing
       the same Net::DNS::Response object to each query. For this reason, you should not modify the
       Net::DNS::Response object in any way lest you break things horribly for a subsequent callback.

       This module is similar in principle to POE::Component::Client::DNS, but does not require POE.

CONSTRUCTOR

       The class method new(...) constructs a new helper object. All arguments are optional. The following
       parameters are recognised as arguments to new():

       QueueSize
           The  size  of  the  query  queue.  If  this is exceeded, further calls to add() will block until some
           responses are received or time out.

       Retries
           The number of times to retry a query before giving up.

       Timeout
           The timeout for an individual query.

METHODS

       $c->add($callback, @query)
           Adds   a   new   query   for   asynchronous   handling.   The   @query   arguments   are   those   to
           Net::DNS::Resolver->bgsend(),  q.v.  This  call  will  block  if the queue is full. When some pending
           responses are received or timeout events occur, the call will unblock.

           The user callback will be called at  some  point  in  the  future,  with  a  Net::DNS::Packet  object
           representing the response. If the query timed out after the specified number of retries, the callback
           will be called with undef.

       $c->await()
           Flushes the queue, that is, waits for and handles all remaining responses.

BUGS

       The test suite does not test query timeouts.

SEE ALSO

       Net::DNS, POE::Component::Client::DNS

COPYRIGHT

       Copyright (c) 2005-2006 Shevek. All rights reserved.

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

perl v5.36.0                                       2022-11-19                               Net::DNS::Async(3pm)