Document Cancellation Safety Guarantees?

[barafael]

The subscriber lends itself really well to usage in loop-selects such as this one:

let stream = client.subscribe(some_subject).await.unwrap();
loop {
    select! {
        _stop = token.cancelled() => {
            info!("Stop requested");
            break;
        }

        Some(request) = stream.next() => {
            do_something(request).await.unwrap();
        }
    }
}

But, one can only do this if the future in question (the implementation of StreamExt::next on Subscriber) is cancellation safe. Else, the next message may get dropped or corrupted. The tokio docs are full of explanations on this, and frequently, items have a # Cancellation Safety section.

Are you making any guarantees about the cancellation safety of the futures in this crate? It would be cool to document those!

[Jarema]

Definately good idea to document those.

In case of Subscriber - it is safe, as under the hood it polls tokio::mpsc::Receiver with self.receiver.poll_recv(cx).