.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::DNS::Async 3pm"
.TH Net::DNS::Async 3pm "2021-01-06" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::DNS::Async \- Asynchronous DNS helper for high volume applications
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Net::DNS::Async;
\&
\&        my $c = new Net::DNS::Async(QueueSize => 20, Retries => 3);
\&
\&        for (...) {
\&                $c\->add(\e&callback, @query);
\&        }
\&        $c\->await();
\&
\&        sub callback {
\&                my $response = shift;
\&                ...
\&        }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::DNS::Async is a fire-and-forget asynchronous \s-1DNS\s0 helper.
That is, the user application adds \s-1DNS\s0 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.
.PP
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.
.PP
This module is similar in principle to POE::Component::Client::DNS,
but does not require \s-1POE.\s0
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
The class method new(...) constructs a new helper object. All arguments
are optional. The following parameters are recognised as arguments
to \fBnew()\fR:
.IP "QueueSize" 4
.IX Item "QueueSize"
The size of the query queue. If this is exceeded, further calls to
\&\fBadd()\fR will block until some responses are received or time out.
.IP "Retries" 4
.IX Item "Retries"
The number of times to retry a query before giving up.
.IP "Timeout" 4
.IX Item "Timeout"
The timeout for an individual query.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$c\->add($callback, @query)" 4
.el .IP "\f(CW$c\fR\->add($callback, \f(CW@query\fR)" 4
.IX Item "$c->add($callback, @query)"
Adds a new query for asynchronous handling. The \f(CW@query\fR arguments are
those to Net::DNS::Resolver\->\fBbgsend()\fR, 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.
.Sp
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.
.ie n .IP "$c\->\fBawait()\fR" 4
.el .IP "\f(CW$c\fR\->\fBawait()\fR" 4
.IX Item "$c->await()"
Flushes the queue, that is, waits for and handles all remaining
responses.
.SH "BUGS"
.IX Header "BUGS"
The test suite does not test query timeouts.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DNS,
POE::Component::Client::DNS
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005\-2006 Shevek. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.