embedded-io-async: clarify cancel safety of Read and Write (#719)

The previous documentation used permissive language ("encouraged",
"implementations should document") that left callers uncertain about
what happens to data in flight when a future is dropped mid-transfer.

Replace the vague encouragement with normative documentation that:
- States explicitly the method is NOT cancel-safe by default
- Describes the concrete failure mode: bytes already received from
  hardware FIFO/DMA may be silently discarded with no error returned
- Uses SHOULD/MUST language consistent with the rest of the trait docs
- Mentions the CancelSafeRead marker trait path for future opt-in
- Gives callers actionable guidance (run future to completion)

This follows the pattern established by Tokio's cancel-safety
documentation and PR #469 ("io: expand docs"), closing the gap that
issue #719 identified.

Fixes #719

Signed-off-by: aki1770-del <aki1770@gmail.com>

Author: aki1770-del

embedded-io-async/src/lib.rs

@@ -46,14 +46,24 @@ pub trait Read: ErrorType {
     /// If `buf.len() == 0`, `read` returns without waiting, with either `Ok(0)` or an error.
     /// The `Ok(0)` doesn't indicate EOF, unlike when called with a non-empty buffer.
     ///
-    /// Implementations are encouraged to make this function side-effect-free on cancel (AKA "cancel-safe"), i.e.
-    /// guarantee that if you cancel (drop) a `read()` future that hasn't completed yet, the stream's
-    /// state hasn't changed (no bytes have been read).
+    /// # Cancel Safety
     ///
-    /// This is not a requirement to allow implementations that read into the user's buffer straight from
-    /// the hardware with e.g. DMA.
+    /// **This method is NOT guaranteed to be cancel-safe.**
     ///
-    /// Implementations should document whether they're actually side-effect-free on cancel or not.
+    /// If a `read()` future is dropped before it completes, bytes that have already been transferred
+    /// from the hardware FIFO or DMA buffer may be silently discarded — no error is returned, and
+    /// no indication is given to the caller that data was lost. The next call to `read()` will return
+    /// bytes received *after* the cancellation point, not the discarded bytes.
+    ///
+    /// Implementations that are able to guarantee cancel safety (i.e. that dropping a pending future
+    /// leaves the stream state unchanged — no bytes consumed) SHOULD document this explicitly and
+    /// MAY implement the `CancelSafeRead` marker trait when it becomes available.
+    ///
+    /// Implementations that cannot guarantee cancel safety (e.g. those that use DMA to write
+    /// directly into the caller's buffer) MUST document this limitation.
+    ///
+    /// Callers that require cancel-safe reads SHOULD use a pattern that ensures the future runs to
+    /// completion (e.g. a dedicated read task) rather than relying on cancel safety.
     async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>;
 
     /// Read the exact number of bytes required to fill `buf`.
@@ -116,14 +126,19 @@ pub trait Write: ErrorType {
     /// If `buf.len() == 0`, `write` returns without waiting, with either `Ok(0)` or an error.
     /// The `Ok(0)` doesn't indicate an error.
     ///
-    /// Implementations are encouraged to make this function side-effect-free on cancel (AKA "cancel-safe"), i.e.
-    /// guarantee that if you cancel (drop) a `write()` future that hasn't completed yet, the stream's
-    /// state hasn't changed (no bytes have been written).
+    /// # Cancel Safety
+    ///
+    /// **This method is NOT guaranteed to be cancel-safe.**
+    ///
+    /// If a `write()` future is dropped before it completes, bytes may have already been submitted
+    /// to the hardware without the caller's knowledge — no error is returned. The number of bytes
+    /// actually written is unknown.
     ///
-    /// This is not a requirement to allow implementations that write from the user's buffer straight to
-    /// the hardware with e.g. DMA.
+    /// Implementations that are able to guarantee cancel safety (i.e. that dropping a pending future
+    /// leaves the stream state unchanged — no bytes written) SHOULD document this explicitly.
     ///
-    /// Implementations should document whether they're actually side-effect-free on cancel or not.
+    /// Implementations that cannot guarantee cancel safety (e.g. those that use DMA directly from
+    /// the caller's buffer) MUST document this limitation.
     async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>;
 
     /// Flush this output stream, ensuring that all intermediately buffered contents reach their destination.