From 9e355b9e52969085ac065e038c82eead70c5b467 Mon Sep 17 00:00:00 2001 From: amab8901 Date: Mon, 27 Feb 2023 16:09:15 +0100 Subject: [PATCH] Add comments --- tokio/src/net/udp.rs | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/tokio/src/net/udp.rs b/tokio/src/net/udp.rs index 4e3862fe49a..8c255f187e1 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -1310,7 +1310,37 @@ impl UdpSocket { .try_io(interest, || self.io.try_io(f)) } - /// lol + /// Reads or writes from the socket using a user-provided IO operation. + /// + /// The readiness of the socket is awaited and when the socket is ready, + /// the provided closure is called. The closure should attempt to perform + /// IO operation on the socket by manually calling the appropriate syscall. + /// If the operation fails because the socket is not actually ready, + /// then the closure should return a `WouldBlock` error, the readiness + /// flag is cleared and the socket readiness is awaited again. This loop + /// repeated until the closure returns an `Ok` or an error that doesn't + /// have the `WouldBlock` value. + /// + /// The closure should only return a `WouldBlock` error if it has performed + /// an IO operation on the socket that failed due to the socket not being + /// ready. Returning a `WouldBlock` error in any other situation will + /// incorrectly clear the readiness flag, which can cause the socket to + /// behave incorrectly. + /// + /// The closure should not perform the IO operation using any of the methods + /// defined on the Tokio `UdpSocket` type, as this will mess with the + /// readiness flag and can cause the socket to behave incorrectly. + /// + /// This method is not intended to be used with combined interests. + /// The closure should perform only one type of IO operation, so it should not + /// require more than one ready state. This method may panic or sleep forever + /// if it is called with a combined interest. + /// + /// Usually, [`readable()`], [`writable()`] or [`ready()`] is used with this function. + /// + /// [`readable()`]: UdpSocket::readable() + /// [`writable()`]: UdpSocket::writable() + /// [`ready()`]: UdpSocket::ready() pub async fn async_io( &self, interest: Interest,