1Mail::SpamAssassin::AsyUnsceLrooCpo(n3t)ributed Perl DocMuamieln:t:aStpiaomnAssassin::AsyncLoop(3)
2
6 Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop
7
9 An asynchronous event loop used for long-running operations, performed
10 "in the background" during the Mail::SpamAssassin::check() scan opera‐
11 tion, such as DNS blocklist lookups.
12
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 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 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 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 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 appropri‐
40 ate. DNS-based lookups can leave it undefined, since DnsRe‐
41 solver::poll_responses() will be called automatically anyway.
42 The code reference will be called with one argument, the $ent
44 object.
45 completed_callback (optional)
47 A code reference which will be called when an asynchronous task
48 (e.g. a DNS lookup) is completed, either normally, or aborted,
49 e.g. by a timeout.
50 When a task has been reported as completed via
52 "set_response_packet()" the response (as provided to
53 "set_response_packet()") is stored in $ent->{response_packet}
54 (possibly undef, its semantics is defined by the caller). When
55 completion is reported via "report_id_complete()" or a task was
56 aborted, the $ent->{response_packet} is guaranteed to be undef.
57 If it is necessary to distinguish between the last two cases,
58 the $ent->{status} may be examined for a string 'ABORTING' or
59 'FINISHED'.
60 The code reference will be called with one argument, the $ent
62 object.
63 zone (optional)
65 A zone specification (typically a DNS zone name - e.g. host,
66 domain, or RBL) which may be used as a key to look up per-zone
67 settings. No semantics on this parameter is imposed by this
68 module.
69 timeout_initial (optional)
71 An initial value of elapsed time for which we are willing to
72 wait for a response (time in seconds, floating point value is
73 allowed). When elapsed time since a query started exceeds the
74 timeout value and there are no other queries to wait for, the
75 query is aborted. The actual timeout value ranges from time‐
76 out_initial and gradually approaches timeout_min (see next
77 parameter) as the number of already completed queries
78 approaches the number of all queries started.
79 If a caller does not explicitly provide this parameter or its
81 value is undefined, a default initial timeout value is settable
82 by a configuration variable rbl_timeout.
83 If a value of the timeout_initial parameter is below time‐
85 out_min, the initial timeout is set to timeout_min.
86 timeout_min (optional)
88 A lower bound (in seconds) to which the actual timeout
89 approaches as the number of queries completed approaches the
90 number of all queries started. Defaults to 0.2 * timeout_ini‐
91 tial.
92 $obj is returned by this method.
94 $obj = $async->get_lookup($key)
96 Retrieve the pending-lookup object for the given key $key.
97 If the lookup is complete, this will return "undef".
99 Note that a lookup is still considered "pending" until "com‐
101 plete_lookups()" is called, even if it has been reported as com‐
102 plete via "set_response_packet()" or "report_id_complete()".
103 @objs = $async->get_pending_lookups()
105 Retrieve the lookup objects for all pending lookups.
106 Note that a lookup is still considered "pending" until "com‐
108 plete_lookups()" is called, even if it has been reported as com‐
109 plete via "set_response_packet()" or "report_id_complete()".
110 $async->log_lookups_timing()
112 Log sorted timing for all completed lookups.
113 $alldone = $async->complete_lookups()
115 Perform a poll of the pending lookups, to see if any are completed;
116 if they are, their <completed_callback> is called with the entry
117 object for that lookup.
118 If there are no lookups remaining, or if too long has elapsed since
120 any results were returned, 1 is returned, otherwise 0.
121 $async->abort_remaining_lookups()
123 Abort any remaining lookups.
124 $async->set_response_packet($id, $pkt, $key, $timestamp)
126 Register a "response packet" for a given query. $id is the ID for
127 the query, and must match the "id" supplied in "start_lookup()".
128 $pkt is the packet object for the response. A parameter $key iden‐
129 tifies an entry in a hash %{$self->{pending_lookups}} where the
130 object which spawned this query can be found, and through which
131 futher information about the query is accessible.
132 If this was called, $pkt will be available in the "completed_call‐
134 back" function as "$ent-<gt"{response_packet}>.
135 One or the other of "set_response_packet()" or "report_id_com‐
137 plete()" should be called, but not both.
138 $async->report_id_complete($id,$key,$key,$timestamp)
140 Register that a query has completed, and is no longer "pending".
141 $id is the ID for the query, and must match the "id" supplied in
142 "start_lookup()".
143 One or the other of "set_response_packet()" or "report_id_com‐
145 plete()" should be called, but not both.
146 $time = $async->last_poll_responses_time()
148 Get the time of the last call to "poll_responses()" (which is
149 called from "complete_lookups()". If "poll_responses()" was never
150 called or "abort_remaining_lookups()" has been called
151 "last_poll_responses_time()" will return undef.
152perl v5.8.8 2008-01-05 Mail::SpamAssassin::AsyncLoop(3)