Document cancel safety

[eric-seppanen]

Would it be possible to document which async fns and trait methods are cancel-safe? I use tokio-tungstenite methods inside the tokio::select! macro, and it's hard for me to tell if this is a supported use case, or if I may be at risk of losing messages.

For example, tokio documents methods that are cancel safe, and adds a # Cancel safety heading to the method documentation (example).

[daniel-abramov]

Reading messages via 'regular methods' provided by Stream/StreamExt is cancel-safe.

For example, tokio documents methods that are cancel safe, and adds a # Cancel safety heading to the method documentation (example).

That's right. Since tokio-tungstenite does not provide "custom" methods for reading messages, but implements the Stream and by extension StreamExt traits, the cancel-safety semantics follows that of the corresponding functions from the aforementioned traits.

Hope this clarifies things a bit!

[eric-seppanen]

It would still be nice to have this in the documentation somewhere, so it doesn't require searching github issues.

I could send a PR if you're amenable; perhaps something like the text you wrote above could live in the lib.rs docs?

I'm not certain what 'regular methods' means exactly. Are there some irregular methods that might not be cancel-safe?

[daniel-abramov]

I'm not against extending our documentation, however, for this particular case, I'm not sure which particular methods you are referring to - currently, if you're reading the messages, you're likely to be using the next() method which is thoroughly documented including the cancelation safety.

tokio-tungstenite does not provide special methods to read messages from the WebSocket stream, but merely implements a couple of traits.

[eric-seppanen]

No problem. I didn't know that all the async fn methods used to access Stream are defined to be cancel safe.