1Mail::SpamAssassin::AsyUnsceLrooCpo(n3t)ributed Perl DocMuamieln:t:aStpiaomnAssassin::AsyncLoop(3)
2
3
4

NAME

6       Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop
7

DESCRIPTION

9       An asynchronous event loop used for long-running operations, performed
10       "in the background" during the Mail::SpamAssassin::check() scan
11       operation, such as DNS blocklist lookups.
12

METHODS

14       $obj = $async->start_lookup($obj)
15           Register the start of a long-running asynchronous lookup operation.
16           $obj is a hash reference containing the following items:
17
18           key (required)
19               A key string, unique to this lookup.  This is what is reported
20               in debug messages, used as the key for "get_lookup()", etc.
21
22           id (required)
23               An ID string, also unique to this lookup.  Typically, this is
24               the DNS packet ID as returned by DnsResolver's "bgsend" method.
25               Sadly, the Net::DNS architecture forces us to keep a separate
26               ID string for this task instead of reusing "key" -- if you are
27               not using DNS lookups through DnsResolver, it should be OK to
28               just reuse "key".
29
30           type (required)
31               A string, typically one word, used to describe the type of
32               lookup in log messages, such as "DNSBL", "MX", "TXT".
33
34           poll_callback (optional)
35               A code reference, which will be called periodically during the
36               background-processing period.  If you will be performing an
37               async lookup on a non-DNS-based service, you will need to
38               implement this so that it checks for new responses and calls
39               "set_response_packet()" or "report_id_complete()" as
40               appropriate.   DNS-based lookups can leave it undefined, since
41               DnsResolver::poll_responses() will be called automatically
42               anyway.
43
44               The code reference will be called with one argument, the $ent
45               object.
46
47           completed_callback (optional)
48               A code reference which will be called when an asynchronous task
49               (e.g. a DNS lookup) is completed, either normally, or aborted,
50               e.g. by a timeout.
51
52               When a task has been reported as completed via
53               "set_response_packet()" the response (as provided to
54               "set_response_packet()") is stored in $ent->{response_packet}
55               (possibly undef, its semantics is defined by the caller). When
56               completion is reported via "report_id_complete()" or a task was
57               aborted, the $ent->{response_packet} is guaranteed to be undef.
58               If it is necessary to distinguish between the last two cases,
59               the $ent->{status} may be examined for a string 'ABORTING' or
60               'FINISHED'.
61
62               The code reference will be called with one argument, the $ent
63               object.
64
65           zone (optional)
66               A zone specification (typically a DNS zone name - e.g. host,
67               domain, or RBL) which may be used as a key to look up per-zone
68               settings. No semantics on this parameter is imposed by this
69               module. Currently used to fetch by-zone timeouts.
70
71           timeout_initial (optional)
72               An initial value of elapsed time for which we are willing to
73               wait for a response (time in seconds, floating point value is
74               allowed). When elapsed time since a query started exceeds the
75               timeout value and there are no other queries to wait for, the
76               query is aborted. The actual timeout value ranges from
77               timeout_initial and gradually approaches timeout_min (see next
78               parameter) as the number of already completed queries
79               approaches the number of all queries started.
80
81               If a caller does not explicitly provide this parameter or its
82               value is undefined, a default initial timeout value is settable
83               by a configuration variable rbl_timeout.
84
85               If a value of the timeout_initial parameter is below
86               timeout_min, the initial timeout is set to timeout_min.
87
88           timeout_min (optional)
89               A lower bound (in seconds) to which the actual timeout
90               approaches as the number of queries completed approaches the
91               number of all queries started.  Defaults to 0.2 *
92               timeout_initial.
93
94           $obj is returned by this method.
95
96       $obj = $async->get_lookup($key)
97           Retrieve the pending-lookup object for the given key $key.
98
99           If the lookup is complete, this will return "undef".
100
101           Note that a lookup is still considered "pending" until
102           "complete_lookups()" is called, even if it has been reported as
103           complete via "set_response_packet()" or "report_id_complete()".
104
105       @objs = $async->get_pending_lookups()
106           Retrieve the lookup objects for all pending lookups.
107
108           Note that a lookup is still considered "pending" until
109           "complete_lookups()" is called, even if it has been reported as
110           complete via "set_response_packet()" or "report_id_complete()".
111
112       $async->log_lookups_timing()
113           Log sorted timing for all completed lookups.
114
115       $alldone = $async->complete_lookups()
116           Perform a poll of the pending lookups, to see if any are completed;
117           if they are, their <completed_callback> is called with the entry
118           object for that lookup.
119
120           If there are no lookups remaining, or if too long has elapsed since
121           any results were returned, 1 is returned, otherwise 0.
122
123       $async->abort_remaining_lookups()
124           Abort any remaining lookups.
125
126       $async->set_response_packet($id, $pkt, $key, $timestamp)
127           Register a "response packet" for a given query.  $id is the ID for
128           the query, and must match the "id" supplied in "start_lookup()".
129           $pkt is the packet object for the response. A parameter $key
130           identifies an entry in a hash %{$self->{pending_lookups}} where the
131           object which spawned this query can be found, and through which
132           futher information about the query is accessible.
133
134           If this was called, $pkt will be available in the
135           "completed_callback" function as "$ent-<gt"{response_packet}>.
136
137           One or the other of "set_response_packet()" or
138           "report_id_complete()" should be called, but not both.
139
140       $async->report_id_complete($id,$key,$key,$timestamp)
141           Register that a query has completed, and is no longer "pending".
142           $id is the ID for the query, and must match the "id" supplied in
143           "start_lookup()".
144
145           One or the other of "set_response_packet()" or
146           "report_id_complete()" should be called, but not both.
147
148       $time = $async->last_poll_responses_time()
149           Get the time of the last call to "poll_responses()" (which is
150           called from "complete_lookups()".  If "poll_responses()" was never
151           called or "abort_remaining_lookups()" has been called
152           "last_poll_responses_time()" will return undef.
153
154
155
156perl v5.10.1                      2010-03-16  Mail::SpamAssassin::AsyncLoop(3)
Impressum