Feature Request: `datagram_readable` &`datagram_writeable` & `try_send/recv_datagram`

[Aderinom]

Hello Team!

At the moment quinn, on datagrams, offers:

• send_datagram - which overwrites datagrams in the send buffer
• send_datagram_wait - which waits until the datagram can be enqueued
• read_datagram - which waits until a datagram has been received

These functions all require:

1. The buffer which should possibly be sent/received on at that moment to already exist -> Possibly wasted work
2. The caller to wait for them/ or accepting data to be lost -> Caller has no control

With this, the User lacks some low level control over the Connection.

I would like to propose adding:

• poll_send_datagram - checking if send is blocked, and if so registering the poller with the datagrams_unblocked notifier.
• poll_read_datagram - checking if receive is blocked, and if so registering the poller with the datagrams_received notifier.

For higher level integration and for the caller to attempt operation without side effect on fail:

• try_send_datagram \ try_receive_datagram - returning a WouldBlock if operation can not be handled without waiting

This would allow a user to check the state of the socket, and decide what to do based on this.
Especially latency sensitive applications or ones which have do internal congestion control could profit from this.

[Ralith]

If you need to register for wakeups, create and poll a future using the existing APIs you've already identified. You can't register to be woken without a future, because that's how multiple tasks waiting for the same event are tracked.

If you don't need to register for wakeups, you can poll the same futures with a no-op waker, but this is usually a design error.

[Aderinom]

Ah, understood, I missed that we need to keep a pinned Notified, so a pure poll won't work.

For what we are trying to do, we would require:

• a way to wait until the transport is readable/writable without side effects
• a way to try to read/write without side effects if it currently would block

Is there a way to do this with the current api?

As a reference - the API we need to implement for our project roughly looks like this:

trait DatagramTransport {
    /// Completes when the transport may have data available.
    async fn readable(&self) -> io::Result<()>;

    /// Completes when the transport may be able to accept a datagram.
    async fn writable(&self) -> io::Result<()>;

    /// Attempts to receive a datagram into the provided buffer.
    /// 
    /// Returns the number of bytes read on success.
    /// Returns WouldBlock if no datagram is currently available.
    fn try_recv(&self, buf: &mut [u8]) -> Result<usize, io::Error>;

    /// Attempts to send a datagram from the provided buffer.
    /// 
    /// Returns the number of bytes sent on success.
    /// Returns WouldBlock if the send buffer is currently full.
    fn try_send(&self, buf: &[u8]) -> Result<usize, io::Error>;
}

[Ralith]

You can easily implement readable/try_recv today:

struct MyTransport {
    connection: quinn::Connection,
    recv_buffer: Option<Bytes>,
}

impl DatagramTransport for MyTransport {
    async fn readable(&self) -> io::Result<()> {
        if self.recv_buffer.is_some() { return Ok(()); }
        self.recv_buffer = Some(self.connection.read_datagram().await?);
        Ok(())
    }
    // ...
}

For try_recv, if recv_buffer is None then you'd create and poll a read_datagram future once with a no-op waker.

The send side is theoretically possible but painful enough to justify some Quinn changes. We currently have pub fn datagram_send_buffer_space(&self) -> usize on Connection, but no way to await some space. A PR introducing a mechanism to wait for the available send buffer space to grow should be simple and would be welcome. See also prior discussion in #1423.

[Aderinom]

If you’d be open to also accepting the readable plus try_recv/try_send functions, I can look into preparing a PR.

The workaround you outlined does cover the read case, but I wouldn’t want to rely on it.

[Ralith]

If you’d be open to also accepting the readable plus try_recv

It's not clear to me that these add anything.

but I wouldn’t want to rely on it.

Why not?

[Aderinom]

It's not clear to me that these add anything.

These are the standard socket primitives.

In the sync world, you can listen to socket events (epoll, select,...), and then send/recv with a possible EWOULDBLOCK.
In the async world, e.g. Tokio’s UDP socket has try_send/try_recv and readable/writable/error.

These are useful when:

• Implementing a generic transport using Quinn (e.g. something like AsyncUdpSocket)
• Working in a poll context
• Needing more precise control over when you allocate buffers
  • for custom congestion control/pacing/backpressure aware applications

These functions are the building blocks for any other flavor of send/recv.
Quinn’s existing Datagrams::send/read already implement this pattern.
The only missing step is to expose them explicitly as try_*.

Why not? [Rely on polling with a no-op waker to simulate try_* functions]

The exact behavior of a Poll from a Future is not part of any contract.
There’s no guarantee Quinn will ever return Ready on the first poll.
At the moment it does, but that depends on implementation details.

I can’t see this as something to rely on outside of a prototype.

---

TLDR: With these changes, Quinn datagrams are a drop-in replacement for any unreliable transports. Without them users have to depend on undocumented behavior.

[djc]

TLDR: With these changes, Quinn datagrams are a drop-in replacement for any unreliable transports. Without them users have to depend on undocumented behavior.

Make a PR that documents the behavior you need? Then we can decide if we think it makes sense to uphold that behavior.

[Aderinom]

Done - see #2366

[djc]

Done - see #2366

Uhh, I asked for a PR that added documentation. You added a whole bunch of code.

[Aderinom]

Assumed it would be easiest to reason over the behavior this way.

Would you like me to write up a more precise specs for the semantics?

[gretchenfrage]

A PR introducing a mechanism to wait for the available send buffer space to grow should be simple and would be welcome. See also prior discussion in #1423.

See also: That sounds related to my eventual goals of #2260 and related work.