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->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
20           Merges duplicate queries automatically, only launches one and calls
21           all related callbacks on answer.
22
23           $name (required)
24               Name to query.
25
26           $type (required)
27               Type to query, A, TXT, NS, etc.
28
29           $class (required/deprecated)
30               Deprecated, ignored, set as undef.
31
32           $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
38               $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
43               $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
50               $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
61                   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
65                   If a value of the timeout_initial parameter is below
66                   timeout_min, the initial timeout is set to timeout_min.
67
68               $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
74               $ent->{key}, $ent->{id} (deprecated)
75                   Deprecated, ignored, automatically generated since 4.0.0.
76
77               $ent->{YOUR_OWN_ITEM}
78                   Any other custom values/objects that you want to pass on to
79                   the answer callback.
80
81           $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
87           %options (required)
88               Hash of options. Only supported and required option is
89               master_deadline:
90
91                 master_deadline => $pms->{master_deadline}
92
93       $ent = $async->start_lookup($ent, $master_deadline)
94           DIRECT USE DEPRECATED since 4.0.0, please use
95           bgsend_and_start_lookup.
96
97       $ent = $async->get_lookup($key)
98           DEPRECATED since 4.0.0. Do not use.
99
100       $async->log_lookups_timing()
101           Log sorted timing for all completed lookups.
102
103       $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
108           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
111       $async->abort_remaining_lookups()
112           Abort any remaining lookups.
113
114       $async->set_response_packet($id, $pkt, $key, $timestamp)
115           For internal use, do not call from plugins.
116
117           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
124           $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
128           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
132       $async->report_id_complete($id,$key,$key,$timestamp)
133           DEPRECATED since 4.0.0. Do not use.
134
135           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
141           One or the other of set_response_packet() or report_id_complete()
142           should be called, but not both.
143
144       $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.
149
150
151
152perl v5.38.0                      2023-07-22  Mail::SpamAssassin::AsyncLoop(3)
Impressum