Explain non-dropped sender recv in docs

[pickfire]

Original senders that are still hanging around could cause
Receiver::recv to not block since this is a potential footgun
for beginners, clarify more on this in the docs for readers to
be aware about it.

Maybe it would be better to show an example of the pattern where drop(tx) is used when it is being cloned multiple times? Although I have seen it in quite a few articles but I am surprised that this part is not very clear with the current words without careful reading.

If the corresponding Sender has disconnected, or it disconnects while this call is blocking, this call will wake up and return Err to indicate that no more messages can ever be received on this channel. However, since channels are buffered, messages sent before the disconnect will still be properly received.

Some words there may seemed similar if I carefully read and relate it but if I am new, I probably does not know "drop" makes it "disconnected". So I mention the words "drop" and "alive" to make it more relatable to lifetime.

[rust-highfive]

r? @dtolnay

(rust-highfive has picked a reviewer for you, use r? to override)

[Dylan-DPC-zz]

r? @KodrAus

[KodrAus]

Thanks for the PR @pickfire!

That original wording is a little unclear that it won’t unblock unless all senders are dropped, isn’t it.

Maybe we could just clarify it a bit more there and avoid sprinkling too many more warnings around?

[pickfire]

That original wording is a little unclear that it won’t unblock unless all senders are dropped, isn’t it.

Where is that? I can't seemed to find it. I did try finding that but I couldn't find anything so I wrote this PR.

Maybe we could just clarify it a bit more there and avoid sprinkling too many more warnings around?

I searched though the file but I can't see it and tried reading the docs again. Can you please point me to the exact line and word you are talking about?

[KodrAus]

@pickfire That's in the docs for the Receiver::recv method.

Having another look through our docs, maybe the section on disconnection in the mpsc module root could also use a clarification that dropping senders means that all instances of it need to be dropped.

What do you think?

[pickfire]

@pickfire That's in the docs for the Receiver::recv method.

Where? I read that part, I had even modified that part in this pull request and yet I didn't saw it. I think this part is quite blur and did not mention the word "drop". If you can point me the exact part out maybe I can switch the keywords to "drop" so it is simpler to understand. Would that be better?

Having another look through our docs, maybe the section on disconnection in the mpsc module root could also use a clarification that dropping senders means that all instances of it need to be dropped.

Adding it to both recv and disconnection would be best. Even better if we show an example of the use case of dropping the sender on the examples section below disconnection.

cc @jyn514 for https://github.com/rust-lang/rust/pull/81833/files#r575693721

[jyn514]

@pickfire why did you ping me? I don't understand what #81833 has to do with this PR.

[pnkfelix]

@jyn514 I'm guessing it was because of the conversation on a review comment there that was subsequently resolved (and thus is remarkably hard to link to directly:

Click to see screen shot of conversation

[pickfire]

@jyn514 Do you see the drop(tx) pattern being explained in the existing docs? If you don't as well, I guess really the current docs is missing this part. Or wait, I think can see it (and relate it) now

This function will always block the current thread if there is no data available and it's possible for more data to be sent.

"it's possible for more data to be sent." but I think not everyone can easily relate that as "all senders have been dropped".
Is it this one?

[jyn514]

Personally, I don't think any documentation changes would have made me not ask questions in #81833 - I'm very unfamiliar with actor-style programming and I wouldn't have thought to look at the API reference for a conceptual overview. I don't think this is a bad change, I just don't have any feedback to give.

[the8472]

Disconnection itself is explained in prose, which code patterns arise from that isn't reflected in the examples since they only use single steps or counted loops. The importance of correct ordering in the drop(tx); thread_guard.join() pattern stems from using channels with unbounded receive loops.

[Dylan-DPC-zz]

minor tidbits

[pickfire]

Disconnection itself is explained in prose, which code patterns arise from that isn't reflected in the examples since they only use single steps or counted loops. The importance of correct ordering in the drop(tx); thread_guard.join() pattern stems from using channels with unbounded receive loops.

I think it would be better if we have an example of using drop to show the cases in which it is necessary for every last transmitter to be dropped. What do you think? Or maybe you already have an example in mind?

[the8472]

I'm not sure how that's different from what I have said, for drop(tx) to have any effect of course all other senders also have to be dropped. I didn't have a very specific example in mind, just something that doesn't use a counted loop.

[pickfire]

I added an example based on tokio drop to show the cases we need drop.

[JohnCSimon]

ping from triage:
@pickfire - can you please address the change request from joshtriplett - or if you have already can you mark the change request as completed?

[pickfire]

Yes, I have addressed the changes requested.

[JohnTitor]

@pickfire Could you squash commits into one? I'll r=josh once it's done as per #80269 (comment).

[pickfire]

Done

[JohnTitor]

Looks like you forgot to push it?

[pickfire]

Ah, thanks. I missed that.

[JohnTitor]

Thanks!

@bors r=joshtriplett rollup

[JohnTitor]

Hmm, bors didn't catch it?
@bors r=joshtriplett

[Mark-Simulacrum]

@bors r=joshtriplett rollup

[bors]

📌 Commit 0f3c7d1 has been approved by joshtriplett