Documentation of AsyncFdReady*Guard::clear_ready is misleading

[oxalica]

Version

tokio 1.35.1

Platform
N/A, documentation only

Description

The documentation of AsyncFdReadyGuard::clear_ready says:

Indicates to tokio that the file descriptor is no longer ready. All internal readiness flags will be cleared, and tokio will wait for the next edge-triggered readiness notification from the OS.

To me, this means that it clear the state and wait for the next notification after the time calling this method. But this implies that the it's incorrect to read to EAGAIN and then clear_ready (as said in docs of clear_ready_matching or try_io implementation), because there could be an edge-notification between the last read and clear_ready, and it would be cleared and lost. Thus clear_ready should be called before calling read to catch all potential notifications.

But after a quick glance to the code, clear_ready seems to only clear readiness flags before the triggered event.

tokio/tokio/src/runtime/io/scheduled_io.rs

Lines 228 to 231 in 46ff363

	if TICK.unpack(current) as u8 != t {
	// Trying to clear readiness with an old event!
	return;
	}

That's to clear readiness before the readiness().await returns, but not notifications happen between readiness() and the next clear_ready(). So the read then clear_ready pattern will not lose any notification.

It's better to address this timing issue in clear_ready and maybe also AsyncFd to be compatible with existing examples and implementations.

[Darksonn]

Yes, we have logic to avoid that race condition. I agree that it would be reasonable to point this out in the documetation.