io: document cancellation safety of AsyncWriteExt::flush (#7364)

tokio/src/io/util/async_write_ext.rs

@@ -1231,6 +1231,16 @@ cfg_io_util! {
         /// It is considered an error if not all bytes could be written due to
         /// I/O errors or EOF being reached.
         ///
+        /// # Cancel safety
+        ///
+        /// This method is cancel safe.
+        ///
+        /// If `flush` is used as the event in a [`tokio::select!`](crate::select)
+        /// statement and some other branch completes first, then the data in the
+        /// buffered data in this `AsyncWrite` may have been partially flushed.
+        /// However, it is guaranteed that the buffer is advanced by the amount of
+        /// bytes that have been partially flushed.
+        ///
         /// # Examples
         ///
         /// ```no_run