Struct Datagrams 

pub struct Datagrams<'a> { /* private fields */ }

API to control datagram traffic

Implementations

impl Datagrams<'_>

pub fn send(&mut self, data: Bytes, drop: bool) -> Result<(), SendDatagramError>

Queue an unreliable, unordered datagram for immediate transmission

If drop is true, previously queued datagrams which are still unsent may be discarded to make space for this datagram, in order of oldest to newest. If drop is false, and there isn’t enough space due to previously queued datagrams, this function will return SendDatagramError::Blocked. Event::DatagramsUnblocked will be emitted once datagrams have been sent.

Returns Err iff a len-byte datagram cannot currently be sent.

pub fn send_many( &mut self, datagrams: &[Bytes], drop: bool, ) -> Result<usize, SendDatagramError>

Queue many unreliable, unordered datagrams for transmission in a single call.

This is the batch analogue of Self::send, avoiding repeated connection checks.

The batch is rejected atomically with the TooLarge error if any datagram in the batch is too large.

drop selects the backpressure behaviour, matching Self::send:

• drop = true drops the oldest queued datagrams to make room, so every element is queued and Ok(datagrams.len()) is returned.
• drop = false queues elements until the send buffer is full, then stops and returns Ok(n) for the n elements queued. The remaining elements are the caller’s to retry once space frees up.

Returns Err if datagrams are unsupported by the peer or disabled locally.

pub fn max_size(&self) -> Option<usize>

Compute the maximum size of datagrams that may be passed to send_datagram

Returns None if datagrams are unsupported by the peer or disabled locally.

This may change over the lifetime of a connection according to variation in the path MTU estimate. The peer can also enforce an arbitrarily small fixed limit, but if the peer’s limit is large this is guaranteed to be a little over a kilobyte at minimum.

Not necessarily the maximum size of received datagrams.

When multipath is enabled, this is calculated using the smallest MTU across all available paths.

pub fn recv(&mut self) -> Option<Bytes>

Receive an unreliable, unordered datagram

pub fn recv_many(&mut self, out: &mut [Bytes]) -> usize

Drain up to out.len() buffered datagrams into out, in arrival order.

This is the batch analogue of Self::recv: a single call takes many datagrams at once. out is filled from the front and overwritten in place; pass a slice of empty Bytes sized to the batch you want. Returns the number of datagrams written, which may be less than out.len() if fewer are buffered (0 if none). Any remaining datagrams stay queued for the next call.

pub fn send_buffer_space(&self) -> usize

Bytes available in the outgoing datagram buffer

When greater than zero, sending a datagram of at most this size is guaranteed not to cause older datagrams to be dropped.