.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::AsyncLoop 3"
.TH Mail::SpamAssassin::AsyncLoop 3 "2010-03-16" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Mail::SpamAssassin::AsyncLoop \- scanner asynchronous event loop
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
An asynchronous event loop used for long-running operations, performed \*(L"in the
background\*(R" during the \fIMail::SpamAssassin::check()\fR scan operation, such as \s-1DNS\s0
blocklist lookups.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$obj = $async\->start_lookup($obj)" 4
.el .IP "$obj = \f(CW$async\fR\->start_lookup($obj)" 4
.IX Item "$obj = $async->start_lookup($obj)"
Register the start of a long-running asynchronous lookup operation. \f(CW$obj\fR
is a hash reference containing the following items:
.RS 4
.IP "key (required)" 4
.IX Item "key (required)"
A key string, unique to this lookup.  This is what is reported in
debug messages, used as the key for \f(CW\*(C`get_lookup()\*(C'\fR, etc.
.IP "id (required)" 4
.IX Item "id (required)"
An \s-1ID\s0 string, also unique to this lookup.  Typically, this is the \s-1DNS\s0 packet \s-1ID\s0
as returned by DnsResolver's \f(CW\*(C`bgsend\*(C'\fR method.  Sadly, the Net::DNS
architecture forces us to keep a separate \s-1ID\s0 string for this task instead of
reusing \f(CW\*(C`key\*(C'\fR \*(-- if you are not using \s-1DNS\s0 lookups through DnsResolver, it
should be \s-1OK\s0 to just reuse \f(CW\*(C`key\*(C'\fR.
.IP "type (required)" 4
.IX Item "type (required)"
A string, typically one word, used to describe the type of lookup in log
messages, such as \f(CW\*(C`DNSBL\*(C'\fR, \f(CW\*(C`MX\*(C'\fR, \f(CW\*(C`TXT\*(C'\fR.
.IP "poll_callback (optional)" 4
.IX Item "poll_callback (optional)"
A code reference, which will be called periodically during the
background-processing period.  If you will be performing an async lookup on a
non-DNS-based service, you will need to implement this so that it checks for
new responses and calls \f(CW\*(C`set_response_packet()\*(C'\fR or \f(CW\*(C`report_id_complete()\*(C'\fR as
appropriate.   DNS-based lookups can leave it undefined, since
\&\fIDnsResolver::poll_responses()\fR will be called automatically anyway.
.Sp
The code reference will be called with one argument, the \f(CW$ent\fR object.
.IP "completed_callback (optional)" 4
.IX Item "completed_callback (optional)"
A code reference which will be called when an asynchronous task (e.g. a
\&\s-1DNS\s0 lookup) is completed, either normally, or aborted, e.g. by a timeout.
.Sp
When a task has been reported as completed via \f(CW\*(C`set_response_packet()\*(C'\fR
the response (as provided to \f(CW\*(C`set_response_packet()\*(C'\fR) is stored in
\&\f(CW$ent\fR\->{response_packet} (possibly undef, its semantics is defined by the
caller). When completion is reported via \f(CW\*(C`report_id_complete()\*(C'\fR or a
task was aborted, the \f(CW$ent\fR\->{response_packet} is guaranteed to be undef.
If it is necessary to distinguish between the last two cases, the
\&\f(CW$ent\fR\->{status} may be examined for a string '\s-1ABORTING\s0' or '\s-1FINISHED\s0'.
.Sp
The code reference will be called with one argument, the \f(CW$ent\fR object.
.IP "zone (optional)" 4
.IX Item "zone (optional)"
A zone specification (typically a \s-1DNS\s0 zone name \- e.g. host, domain, or \s-1RBL\s0)
which may be used as a key to look up per-zone settings. No semantics on this
parameter is imposed by this module. Currently used to fetch by-zone timeouts.
.IP "timeout_initial (optional)" 4
.IX Item "timeout_initial (optional)"
An initial value of elapsed time for which we are willing to wait for a
response (time in seconds, floating point value is allowed). When elapsed
time since a query started exceeds the timeout value and there are no other
queries to wait for, the query is aborted. The actual timeout value ranges
from timeout_initial and gradually approaches timeout_min (see next parameter)
as the number of already completed queries approaches the number of all
queries started.
.Sp
If a caller does not explicitly provide this parameter or its value is
undefined, a default initial timeout value is settable by a configuration
variable rbl_timeout.
.Sp
If a value of the timeout_initial parameter is below timeout_min, the initial
timeout is set to timeout_min.
.IP "timeout_min (optional)" 4
.IX Item "timeout_min (optional)"
A lower bound (in seconds) to which the actual timeout approaches as the
number of queries completed approaches the number of all queries started.
Defaults to 0.2 * timeout_initial.
.RE
.RS 4
.Sp
\&\f(CW$obj\fR is returned by this method.
.RE
.ie n .IP "$obj = $async\->get_lookup($key)" 4
.el .IP "$obj = \f(CW$async\fR\->get_lookup($key)" 4
.IX Item "$obj = $async->get_lookup($key)"
Retrieve the pending-lookup object for the given key \f(CW$key\fR.
.Sp
If the lookup is complete, this will return \f(CW\*(C`undef\*(C'\fR.
.Sp
Note that a lookup is still considered \*(L"pending\*(R" until \f(CW\*(C`complete_lookups()\*(C'\fR is
called, even if it has been reported as complete via \f(CW\*(C`set_response_packet()\*(C'\fR
or \f(CW\*(C`report_id_complete()\*(C'\fR.
.ie n .IP "@objs = $async\fR\->\fIget_pending_lookups()" 4
.el .IP "@objs = \f(CW$async\fR\->\fIget_pending_lookups()\fR" 4
.IX Item "@objs = $async->get_pending_lookups()"
Retrieve the lookup objects for all pending lookups.
.Sp
Note that a lookup is still considered \*(L"pending\*(R" until \f(CW\*(C`complete_lookups()\*(C'\fR is
called, even if it has been reported as complete via \f(CW\*(C`set_response_packet()\*(C'\fR
or \f(CW\*(C`report_id_complete()\*(C'\fR.
.IP "$async\->\fIlog_lookups_timing()\fR" 4
.IX Item "$async->log_lookups_timing()"
Log sorted timing for all completed lookups.
.ie n .IP "$alldone = $async\fR\->\fIcomplete_lookups()" 4
.el .IP "$alldone = \f(CW$async\fR\->\fIcomplete_lookups()\fR" 4
.IX Item "$alldone = $async->complete_lookups()"
Perform a poll of the pending lookups, to see if any are completed; if they
are, their <completed_callback> is called with the entry object for that
lookup.
.Sp
If there are no lookups remaining, or if too long has elapsed since any results
were returned, \f(CW1\fR is returned, otherwise \f(CW0\fR.
.IP "$async\->\fIabort_remaining_lookups()\fR" 4
.IX Item "$async->abort_remaining_lookups()"
Abort any remaining lookups.
.ie n .IP "$async\->set_response_packet($id, $pkt\fR, \f(CW$key\fR, \f(CW$timestamp)" 4
.el .IP "$async\->set_response_packet($id, \f(CW$pkt\fR, \f(CW$key\fR, \f(CW$timestamp\fR)" 4
.IX Item "$async->set_response_packet($id, $pkt, $key, $timestamp)"
Register a \*(L"response packet\*(R" for a given query.  \f(CW$id\fR is the \s-1ID\s0 for the
query, and must match the \f(CW\*(C`id\*(C'\fR supplied in \f(CW\*(C`start_lookup()\*(C'\fR. \f(CW$pkt\fR is the
packet object for the response. A parameter \f(CW$key\fR identifies an entry in a
hash %{$self\->{pending_lookups}} where the object which spawned this query can
be found, and through which futher information about the query is accessible.
.Sp
If this was called, \f(CW$pkt\fR will be available in the \f(CW\*(C`completed_callback\*(C'\fR
function as \f(CW\*(C`$ent\-<gt\*(C'\fR{response_packet}>.
.Sp
One or the other of \f(CW\*(C`set_response_packet()\*(C'\fR or \f(CW\*(C`report_id_complete()\*(C'\fR
should be called, but not both.
.IP "$async\->report_id_complete($id,$key,$key,$timestamp)" 4
.IX Item "$async->report_id_complete($id,$key,$key,$timestamp)"
Register that a query has completed, and is no longer \*(L"pending\*(R". \f(CW$id\fR is the
\&\s-1ID\s0 for the query, and must match the \f(CW\*(C`id\*(C'\fR supplied in \f(CW\*(C`start_lookup()\*(C'\fR.
.Sp
One or the other of \f(CW\*(C`set_response_packet()\*(C'\fR or \f(CW\*(C`report_id_complete()\*(C'\fR
should be called, but not both.
.ie n .IP "$time = $async\fR\->\fIlast_poll_responses_time()" 4
.el .IP "$time = \f(CW$async\fR\->\fIlast_poll_responses_time()\fR" 4
.IX Item "$time = $async->last_poll_responses_time()"
Get the time of the last call to \f(CW\*(C`poll_responses()\*(C'\fR (which is called
from \f(CW\*(C`complete_lookups()\*(C'\fR.  If \f(CW\*(C`poll_responses()\*(C'\fR was never called or
\&\f(CW\*(C`abort_remaining_lookups()\*(C'\fR has been called \f(CW\*(C`last_poll_responses_time()\*(C'\fR
will return undef.