Cancellation safety of `Read::read` and `Write::write` in embedded-io-async

[ivmarkov]

The current documentation of the read and write methods in e-hal async leaves the cancellation safety explicitly down to implementors:

• embedded-hal/embedded-io-async/src/lib.rs

  Line 49 in cb1f73e

  /// Implementations are encouraged to make this function side-effect-free on cancel (AKA "cancel-safe"), i.e.

• embedded-hal/embedded-io-async/src/lib.rs

  Line 119 in cb1f73e

  /// Implementations are encouraged to make this function side-effect-free on cancel (AKA "cancel-safe"), i.e.

I wonder whether "encouraged" and "leave it down to implementers to document" is good enough though?
Tokio - in contrast - is pretty explicit about that:

• https://docs.rs/tokio/latest/tokio/io/trait.AsyncReadExt.html#cancel-safety
• https://docs.rs/tokio/latest/tokio/io/trait.AsyncWriteExt.html#cancel-safety

I wonder whether we actually need two pairs of traits instead? I.e. for Read:

• ReadNonCancelSafe (let's leave the name bike-shedding as well as whether the non-cancel safe or the cancel-safe variant shall be named Read for later, shall we?) - with the current Read semantics and the "encouragement" paragraph replaced with an explicit "read is NOT cancel safe"
• Read - with an enforced cancellation-safe semantics, just like AsyncReadExt from tokio?

This way, implementations users that do care about cancellation safety would demand Read.
Those that don't might require the weaker ReadNonCancelSafe.

(This all in the context of stabilizing embedded-io-async.)

[adamgreig]

We discussed this point a bunch in the meeting today (logs). No firm conclusions but there was a suggestion we could keep Read as-is (not necessarily cancel safe) and later add CancelSafeRead: Read as a marker trait for impls to add when their Read happens to be cancel safe; this is a non-breaking change for both us and impls in the future.