NAME
    Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop

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

METHODS
    $ent = $async->bgsend_and_start_lookup($name, $type, $class, $ent, $cb,
    %options)
        Launch async DNS lookups. This is the only official method supported
        for plugins since version 4.0.0. Do not use bgsend and start_lookup
        separately.

        Merges duplicate queries automatically, only launches one and calls
        all related callbacks on answer.

        $name (required)
            Name to query.

        $type (required)
            Type to query, A, TXT, NS, etc.

        $class (required/deprecated)
            Deprecated, ignored, set as undef.

        $ent is a required hash reference containing the following items:

            $ent->{rulename} (required)
                The rulename that started and/or depends on this query.
                Required for rule dependencies to work correctly. Can be a
                single rulename, or array of multiple rulenames.

            $ent->{type} (optional)
                A string, typically one word, used to describe the type of
                lookup in log messages, such as "DNSBL", "URIBL-A". If not
                defined, default is value of $type.

            $ent->{zone} (optional)
                A zone specification (typically a DNS zone name - e.g. host,
                domain, or RBL) which may be used as a key to look up
                per-zone settings. No semantics on this parameter is imposed
                by this module. Currently used to fetch by-zone timeouts
                (from rbl_timeout setting). Defaults to $name.

            $ent->{timeout_initial} (optional)
                An initial value of elapsed time for which we are willing to
                wait for a response (time in seconds, floating point value
                is allowed). When elapsed time since a query started exceeds
                the timeout value and there are no other queries to wait
                for, the query is aborted. The actual timeout value ranges
                from timeout_initial and gradually approaches timeout_min
                (see next parameter) as the number of already completed
                queries approaches the number of all queries started.

                If a caller does not explicitly provide this parameter or
                its value is undefined, a default initial timeout value is
                settable by a configuration variable rbl_timeout.

                If a value of the timeout_initial parameter is below
                timeout_min, the initial timeout is set to timeout_min.

            $ent->{timeout_min} (optional)
                A lower bound (in seconds) to which the actual timeout
                approaches as the number of queries completed approaches the
                number of all queries started. Defaults to 0.2 *
                timeout_initial.

            $ent->{key}, $ent->{id} (deprecated)
                Deprecated, ignored, automatically generated since 4.0.0.

            $ent->{YOUR_OWN_ITEM}
                Any other custom values/objects that you want to pass on to
                the answer callback.

        $cb (required)
            Callback function for answer, called as $cb->($ent, $pkt). $ent
            is the same object that bgsend_and_start_lookup was called with.
            $pkt is the packet object for the response, Net::DNS:RR objects
            can be found from $pkt->answer.

        %options (required)
            Hash of options. Only supported and required option is
            master_deadline:

              master_deadline => $pms->{master_deadline}

    $ent = $async->start_lookup($ent, $master_deadline)
        DIRECT USE DEPRECATED since 4.0.0, please use
        bgsend_and_start_lookup.

    $ent = $async->get_lookup($key)
        DEPRECATED since 4.0.0. Do not use.

    $async->log_lookups_timing()
        Log sorted timing for all completed lookups.

    $alldone = $async->complete_lookups()
        Perform a poll of the pending lookups, to see if any are completed.
        Callbacks on completed queries will be called from poll_responses().

        If there are no lookups remaining, or if too much time has elapsed
        since any results were returned, 1 is returned, otherwise 0.

    $async->abort_remaining_lookups()
        Abort any remaining lookups.

    $async->set_response_packet($id, $pkt, $key, $timestamp)
        For internal use, do not call from plugins.

        Register a "response packet" for a given query. $id is the ID for
        the query, and must match the "id" supplied in "start_lookup()".
        $pkt is the packet object for the response. A parameter $key
        identifies an entry in a hash %{$self->{pending_lookups}} where the
        object which spawned this query can be found, and through which
        further information about the query is accessible.

        $pkt may be undef, indicating that no response packet is available,
        but a query has completed (e.g. was aborted or dismissed) and is no
        longer "pending".

        The DNS resolver's response packet $pkt will be made available to a
        callback subroutine through its argument as well as in
        "$ent->{response_packet}".

    $async->report_id_complete($id,$key,$key,$timestamp)
        DEPRECATED since 4.0.0. Do not use.

        Legacy. Equivalent to
        $self->set_response_packet($id,undef,$key,$timestamp), i.e.
        providing undef as a response packet. Register that a query has
        completed and is no longer "pending". $id is the ID for the query,
        and must match the "id" supplied in "start_lookup()".

        One or the other of "set_response_packet()" or
        "report_id_complete()" should be called, but not both.

    $time = $async->last_poll_responses_time()
        Get the time of the last call to "poll_responses()" (which is called
        from "complete_lookups()". If "poll_responses()" was never called or
        "abort_remaining_lookups()" has been called
        "last_poll_responses_time()" will return undef.