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
11 operation, such as DNS blocklist lookups.
12
14 $ent = $async->bgsend_and_start_lookup($name, $type, $class, $ent, $cb,
15 %options)
16 Launch async DNS lookups. This is the only official method
17 supported for plugins since version 4.0.0. Do not use bgsend and
18 start_lookup separately.
19 Merges duplicate queries automatically, only launches one and calls
21 all related callbacks on answer.
22 $name (required)
24 Name to query.
25 $type (required)
27 Type to query, A, TXT, NS, etc.
28 $class (required/deprecated)
30 Deprecated, ignored, set as undef.
31 $ent is a required hash reference containing the following items:
33 $ent->{rulename} (required)
34 The rulename that started and/or depends on this query.
35 Required for rule dependencies to work correctly. Can be a
36 single rulename, or array of multiple rulenames.
37 $ent->{type} (optional)
39 A string, typically one word, used to describe the type of
40 lookup in log messages, such as "DNSBL", "URIBL-A". If not
41 defined, default is value of $type.
42 $ent->{zone} (optional)
44 A zone specification (typically a DNS zone name - e.g.
45 host, domain, or RBL) which may be used as a key to look up
46 per-zone settings. No semantics on this parameter is
47 imposed by this module. Currently used to fetch by-zone
48 timeouts (from rbl_timeout setting). Defaults to $name.
49 $ent->{timeout_initial} (optional)
51 An initial value of elapsed time for which we are willing
52 to wait for a response (time in seconds, floating point
53 value is allowed). When elapsed time since a query started
54 exceeds the timeout value and there are no other queries to
55 wait for, the query is aborted. The actual timeout value
56 ranges from timeout_initial and gradually approaches
57 timeout_min (see next parameter) as the number of already
58 completed queries approaches the number of all queries
59 started.
60 If a caller does not explicitly provide this parameter or
62 its value is undefined, a default initial timeout value is
63 settable by a configuration variable rbl_timeout.
64 If a value of the timeout_initial parameter is below
66 timeout_min, the initial timeout is set to timeout_min.
67 $ent->{timeout_min} (optional)
69 A lower bound (in seconds) to which the actual timeout
70 approaches as the number of queries completed approaches
71 the number of all queries started. Defaults to 0.2 *
72 timeout_initial.
73 $ent->{key}, $ent->{id} (deprecated)
75 Deprecated, ignored, automatically generated since 4.0.0.
76 $ent->{YOUR_OWN_ITEM}
78 Any other custom values/objects that you want to pass on to
79 the answer callback.
80 $cb (required)
82 Callback function for answer, called as $cb->($ent, $pkt).
83 $ent is the same object that bgsend_and_start_lookup was called
84 with. $pkt is the packet object for the response, Net::DNS:RR
85 objects can be found from $pkt->answer.
86 %options (required)
88 Hash of options. Only supported and required option is
89 master_deadline:
90 master_deadline => $pms->{master_deadline}
92 $ent = $async->start_lookup($ent, $master_deadline)
94 DIRECT USE DEPRECATED since 4.0.0, please use
95 bgsend_and_start_lookup.
96 $ent = $async->get_lookup($key)
98 DEPRECATED since 4.0.0. Do not use.
99 $async->log_lookups_timing()
101 Log sorted timing for all completed lookups.
102 $alldone = $async->complete_lookups()
104 Perform a poll of the pending lookups, to see if any are completed.
105 Callbacks on completed queries will be called from
106 poll_responses().
107 If there are no lookups remaining, or if too much time has elapsed
109 since any results were returned, 1 is returned, otherwise 0.
110 $async->abort_remaining_lookups()
112 Abort any remaining lookups.
113 $async->set_response_packet($id, $pkt, $key, $timestamp)
115 For internal use, do not call from plugins.
116 Register a "response packet" for a given query. $id is the ID for
118 the query, and must match the "id" supplied in start_lookup(). $pkt
119 is the packet object for the response. A parameter $key identifies
120 an entry in a hash %{$self->{pending_lookups}} where the object
121 which spawned this query can be found, and through which further
122 information about the query is accessible.
123 $pkt may be undef, indicating that no response packet is available,
125 but a query has completed (e.g. was aborted or dismissed) and is no
126 longer "pending".
127 The DNS resolver's response packet $pkt will be made available to a
129 callback subroutine through its argument as well as in
130 "$ent-<gt"{response_packet}>.
131 $async->report_id_complete($id,$key,$key,$timestamp)
133 DEPRECATED since 4.0.0. Do not use.
134 Legacy. Equivalent to
136 $self->set_response_packet($id,undef,$key,$timestamp), i.e.
137 providing undef as a response packet. Register that a query has
138 completed and is no longer "pending". $id is the ID for the query,
139 and must match the "id" supplied in start_lookup().
140 One or the other of set_response_packet() or report_id_complete()
142 should be called, but not both.
143 $time = $async->last_poll_responses_time()
145 Get the time of the last call to poll_responses() (which is called
146 from complete_lookups(). If poll_responses() was never called or
147 abort_remaining_lookups() has been called
148 last_poll_responses_time() will return undef.
149perl v5.36.0 2023-01-21 Mail::SpamAssassin::AsyncLoop(3)