From 328bd049f6a9c2819ee6bcb6752dd57a3a456aee Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Wed, 28 May 2025 04:00:33 -0700 Subject: [PATCH] io: clarify behavior of seeking when `start_seek` is not used (#7366) --- tokio/src/io/async_seek.rs | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/tokio/src/io/async_seek.rs b/tokio/src/io/async_seek.rs index 1b57b7890..fbd1eafa0 100644 --- a/tokio/src/io/async_seek.rs +++ b/tokio/src/io/async_seek.rs @@ -34,11 +34,17 @@ pub trait AsyncSeek { /// Waits for a seek operation to complete. /// - /// If the seek operation completed successfully, - /// this method returns the new position from the start of the stream. - /// That position can be used later with [`SeekFrom::Start`]. Repeatedly - /// calling this function without calling `start_seek` might return the - /// same result. + /// If the seek operation completed successfully, this method returns the + /// new position from the start of the stream. That position can be used + /// later with [`SeekFrom::Start`]. + /// + /// The position returned by calling this method can only be relied on right + /// after `start_seek`. If you have changed the position by e.g. reading or + /// writing since calling `start_seek`, then it is unspecified whether the + /// returned position takes that position change into account. Similarly, if + /// `start_seek` has never been called, then it is unspecified whether + /// `poll_complete` returns the actual position or some other placeholder + /// value (such as 0). /// /// # Errors ///