Struct Query 

pub struct Query<I, AN, EV> { /* private fields */ }

Available on crate features alloc or no-atomic or std only.

Query state machine. One per outstanding query.

Implementations

impl<I, AN, EV> Query<I, AN, EV>

where I: Instant, AN: Pool<CollectedAnswer>, EV: Pool<QueryUpdate>,

pub fn with_max_answers(self, max: usize) -> Self

Override the maximum number of collected answers (default 256).

When the pool reaches this limit the oldest entry (FIFO) is evicted to make room for the incoming answer. Setting max to 0 disables collection entirely.

pub fn set_max_answers(&mut self, max: usize)

Set the maximum number of collected answers in place. Same semantics as Self::with_max_answers but for use after construction (e.g. by Endpoint::try_start_query when threading a QuerySpec::max_answers).

pub const fn handle(&self) -> QueryHandle

Returns the handle assigned at start.

pub fn qname(&self) -> &Name

Returns the queried name.

pub const fn qtype(&self) -> ResourceType

Returns the queried record type.

pub const fn qclass(&self) -> ResourceClass

Returns the queried class.

pub const fn txid(&self) -> u16

Returns the transaction id used on outgoing queries.

pub fn handle_event(&mut self, event: QueryEvent<'_>)

Process an event routed to this query by the Endpoint.

pub fn poll_timeout(&self) -> Option<I>

Next deadline for handle_timeout.

Returns the earlier of next_deadline (next retry) and timeout_deadline (absolute query cancellation). A driver that sleeps until this instant is guaranteed to wake in time to fire the absolute timeout even when the next retry is scheduled far in the future.

pub fn handle_timeout(&mut self, now: I) -> Result<(), HandleTimeoutError>

Drive timer-based transitions.

pub fn poll_transmit( &mut self, _now: I, buf: &mut [u8], ) -> Result<Option<Transmit>, TransmitError>

Produce the next outgoing datagram, if any. Writes into buf.

Returns Ok(None) when the query is done or when no send is currently due (i.e. transmit_pending is false). A single call per scheduled deadline tick is guaranteed: the pending flag is cleared after the datagram is built, so a driver looping on this method will not re-send the query until the next handle_timeout fires.

pub fn note_transmit_result(&mut self, now: I, delivered: bool)

Report the result of sending the datagram most recently produced by Self::poll_transmit. The driver calls this after a send, with delivered = true when at least one socket send succeeded.

On a delivered send this counts the transmission against the §5.2 retry budget and schedules the next retransmit (backoff: +1s, doubling, capped at 60s). On a failed send the budget is NOT consumed and the query is re-armed to re-attempt at the same interval — so a transient or total send failure retries with backoff (no tight spin) and a query can never reach its retry-budget timeout having put nothing on the wire.

pub fn note_duplicate_question(&mut self, now: I) -> bool

RFC 6762 §7.3 duplicate-question suppression. Another host has multicast the SAME question that this query is ABOUT TO (re)transmit. Treat the peer’s query as our own (“treat its own query as having been sent”): consume this retry slot and arm the next retransmit on the normal backoff, without putting a redundant query on the wire — the peer’s query elicits the multicast answers we want.

A retransmit is “imminent” either when it is already armed (transmit_pending, the window between handle_timeout firing and poll_transmit draining) OR when its next_deadline is already due but not yet armed — the latter covers drivers that pump received packets BEFORE firing query timeouts, so suppression does not depend on that ordering. Either way it consumes exactly one retry slot: transmit_pending is cleared and the due deadline is pushed forward, so a second duplicate in the same slot is a no-op — suppression is idempotent per slot.

The retry budget advances exactly as a real send would (and the query retires via MAX_RETRIES here too), so a continuously-duplicated query still progresses to its terminal timeout instead of being deferred forever. An in-flight (awaiting-confirm) send is left alone.

Returns true if a transmit slot was actually consumed (i.e. real suppression happened) and false if the call was a no-op (query is done, awaiting send confirmation, or no send was imminent). Callers use the return value to decide whether to bump the duplicate_questions_suppressed counter.

pub fn poll(&mut self) -> Option<QueryUpdate>

Drain a pending app-level update.

pub const fn is_done(&self) -> bool

Has the query reached a terminal state? Backstop for Endpoint::poll_query under EV-pool pressure: if handle_timeout cannot push the terminal QueryUpdate::Timeout, Endpoint::poll_query falls back to this flag and synthesises Timeout. External callers normally do NOT need to consult this directly — drive Endpoint::poll_query and react to its terminal return value.

pub fn collected_answers(&self) -> impl Iterator<Item = &CollectedAnswer> + '_

Iterate the answers collected so far by this query.

pub fn accepted_count(&self) -> u64

Total number of answers ever accepted by this query, including ones already evicted by the max_answers cap.

Equal to the next sequence number to be assigned, so it is monotonic and >= the highest seq currently in Self::collected_answers. A consumer that delivers answers by ascending seq can compare this against the count it has observed to detect (and count) answers the cap evicted before they were read.