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       $ent = $async->start_lookup($ent, $master_deadline)
15           Register the start of a long-running asynchronous lookup operation.
16           $ent 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           zone (optional)
35               A zone specification (typically a DNS zone name - e.g. host,
36               domain, or RBL) which may be used as a key to look up per-zone
37               settings. No semantics on this parameter is imposed by this
38               module. Currently used to fetch by-zone timeouts.
39
40           timeout_initial (optional)
41               An initial value of elapsed time for which we are willing to
42               wait for a response (time in seconds, floating point value is
43               allowed). When elapsed time since a query started exceeds the
44               timeout value and there are no other queries to wait for, the
45               query is aborted. The actual timeout value ranges from
46               timeout_initial and gradually approaches timeout_min (see next
47               parameter) as the number of already completed queries
48               approaches the number of all queries started.
49
50               If a caller does not explicitly provide this parameter or its
51               value is undefined, a default initial timeout value is settable
52               by a configuration variable rbl_timeout.
53
54               If a value of the timeout_initial parameter is below
55               timeout_min, the initial timeout is set to timeout_min.
56
57           timeout_min (optional)
58               A lower bound (in seconds) to which the actual timeout
59               approaches as the number of queries completed approaches the
60               number of all queries started.  Defaults to 0.2 *
61               timeout_initial.
62
63           $ent is returned by this method, with its contents augmented by
64           additional information.
65
66       $ent = $async->bgsend_and_start_lookup($domain, $type, $class, $ent,
67       $cb, %options)
68           A common idiom: calls "bgsend", followed by a call to
69           "start_lookup", returning the argument $ent object as modified by
70           "start_lookup" and filled-in with a query ID.
71
72       $ent = $async->get_lookup($key)
73           Retrieve the pending-lookup object for the given key $key.
74
75           If the lookup is complete, this will return "undef".
76
77           Note that a lookup is still considered "pending" until
78           "complete_lookups()" is called, even if it has been reported as
79           complete via "set_response_packet()".
80
81       $async->log_lookups_timing()
82           Log sorted timing for all completed lookups.
83
84       $alldone = $async->complete_lookups()
85           Perform a poll of the pending lookups, to see if any are completed.
86           Callbacks on completed queries will be called from
87           poll_responses().
88
89           If there are no lookups remaining, or if too much time has elapsed
90           since any results were returned, 1 is returned, otherwise 0.
91
92       $async->abort_remaining_lookups()
93           Abort any remaining lookups.
94
95       $async->set_response_packet($id, $pkt, $key, $timestamp)
96           Register a "response packet" for a given query.  $id is the ID for
97           the query, and must match the "id" supplied in "start_lookup()".
98           $pkt is the packet object for the response. A parameter $key
99           identifies an entry in a hash %{$self->{pending_lookups}} where the
100           object which spawned this query can be found, and through which
101           further information about the query is accessible.
102
103           $pkt may be undef, indicating that no response packet is available,
104           but a query has completed (e.g. was aborted or dismissed) and is no
105           longer "pending".
106
107           The DNS resolver's response packet $pkt will be made available to a
108           callback subroutine through its argument as well as in
109           "$ent-<gt"{response_packet}>.
110
111       $async->report_id_complete($id,$key,$key,$timestamp)
112           Legacy. Equivalent to
113           $self->set_response_packet($id,undef,$key,$timestamp), i.e.
114           providing undef as a response packet. Register that a query has
115           completed and is no longer "pending". $id is the ID for the query,
116           and must match the "id" supplied in "start_lookup()".
117
118           One or the other of "set_response_packet()" or
119           "report_id_complete()" should be called, but not both.
120
121       $time = $async->last_poll_responses_time()
122           Get the time of the last call to "poll_responses()" (which is
123           called from "complete_lookups()".  If "poll_responses()" was never
124           called or "abort_remaining_lookups()" has been called
125           "last_poll_responses_time()" will return undef.
126
127
128
129perl v5.32.1                      2021-03-25  Mail::SpamAssassin::AsyncLoop(3)
Impressum