Document cancel-safety of stream I/O operations

quinn/src/recv_stream.rs

@@ -21,6 +21,13 @@ use crate::{
 /// - A variant of [`ReadError`] has been yielded by a read call
 /// - [`stop()`] was called explicitly
 ///
+/// # Cancellation
+///
+/// A `read` method is said to be *cancel-safe* when dropping its future before the future becomes
+/// ready cannot lead to loss of stream data. This is true of methods which succeed immediately when
+/// any progress is made, and is not true of methods which might need to perform multiple reads
+/// internally before succeeding. Each `read` method documents whether it is cancel-safe.
+///
 /// # Common issues
 ///
 /// ## Data never received on a locally-opened stream
@@ -111,6 +118,8 @@ impl RecvStream {
     /// Read data contiguously from the stream.
     ///
     /// Yields the number of bytes read into `buf` on success, or `None` if the stream was finished.
+    ///
+    /// This operation is cancel-safe.
     pub async fn read(&mut self, buf: &mut [u8]) -> Result<Option<usize>, ReadError> {
         Read {
             stream: self,
@@ -121,7 +130,7 @@ impl RecvStream {
 
     /// Read an exact number of bytes contiguously from the stream.
     ///
-    /// See [`read()`] for details.
+    /// See [`read()`] for details. This operation is *not* cancel-safe.
     ///
     /// [`read()`]: RecvStream::read
     pub async fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), ReadExactError> {
@@ -172,6 +181,8 @@ impl RecvStream {
     ///
     /// Slightly more efficient than `read` due to not copying. Chunk boundaries do not correspond
     /// to peer writes, and hence cannot be used as framing.
+    ///
+    /// This operation is cancel-safe.
     pub async fn read_chunk(
         &mut self,
         max_length: usize,
@@ -206,6 +217,8 @@ impl RecvStream {
     ///
     /// Slightly more efficient than `read` due to not copying. Chunk boundaries
     /// do not correspond to peer writes, and hence cannot be used as framing.
+    ///
+    /// This operation is cancel-safe.
     pub async fn read_chunks(&mut self, bufs: &mut [Bytes]) -> Result<Option<usize>, ReadError> {
         ReadChunks { stream: self, bufs }.await
     }
@@ -248,6 +261,8 @@ impl RecvStream {
     /// If unordered reads have already been made, the resulting buffer may have gaps containing
     /// arbitrary data.
     ///
+    /// This operation is *not* cancel-safe.
+    ///
     /// [`ReadToEndError::TooLong`]: crate::ReadToEndError::TooLong
     pub async fn read_to_end(&mut self, size_limit: usize) -> Result<Vec<u8>, ReadToEndError> {
         ReadToEnd {

quinn/src/send_stream.rs

@@ -20,6 +20,14 @@ use crate::{
 /// If dropped, streams that haven't been explicitly [`reset()`] will continue to (re)transmit
 /// previously written data until it has been fully acknowledged or the connection is closed.
 ///
+/// # Cancellation
+///
+/// A `write` method is said to be *cancel-safe* when dropping its future before the future becomes
+/// ready will always result in no data being written to the stream. This is true of methods which
+/// succeed immediately when any progress is made, and is not true of methods which might need to
+/// perform multiple writes internally before succeeding. Each `write` method documents whether it is
+/// cancel-safe.
+///
 /// [`reset()`]: SendStream::reset
 #[derive(Debug)]
 pub struct SendStream {
@@ -43,11 +51,15 @@ impl SendStream {
     ///
     /// Yields the number of bytes written on success. Congestion and flow control may cause this to
     /// be shorter than `buf.len()`, indicating that only a prefix of `buf` was written.
+    ///
+    /// This operation is cancel-safe.
     pub async fn write(&mut self, buf: &[u8]) -> Result<usize, WriteError> {
         Write { stream: self, buf }.await
     }
 
     /// Convenience method to write an entire buffer to the stream
+    ///
+    /// This operation is *not* cancel-safe.
     pub async fn write_all(&mut self, buf: &[u8]) -> Result<(), WriteError> {
         WriteAll { stream: self, buf }.await
     }
@@ -57,11 +69,15 @@ impl SendStream {
     /// Yields the number of bytes and chunks written on success.
     /// Congestion and flow control may cause this to be shorter than `buf.len()`,
     /// indicating that only a prefix of `bufs` was written
+    ///
+    /// This operation is cancel-safe.
     pub async fn write_chunks(&mut self, bufs: &mut [Bytes]) -> Result<Written, WriteError> {
         WriteChunks { stream: self, bufs }.await
     }
 
     /// Convenience method to write a single chunk in its entirety to the stream
+    ///
+    /// This operation is *not* cancel-safe.
     pub async fn write_chunk(&mut self, buf: Bytes) -> Result<(), WriteError> {
         WriteChunk {
             stream: self,
@@ -71,6 +87,8 @@ impl SendStream {
     }
 
     /// Convenience method to write an entire list of chunks to the stream
+    ///
+    /// This operation is *not* cancel-safe.
     pub async fn write_all_chunks(&mut self, bufs: &mut [Bytes]) -> Result<(), WriteError> {
         WriteAllChunks {
             stream: self,