-
Notifications
You must be signed in to change notification settings - Fork 12.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Explain non-dropped sender recv in docs #80269
Conversation
r? @dtolnay (rust-highfive has picked a reviewer for you, use r? to override) |
r? @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? |
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.
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? |
@pickfire That's in the docs for the Having another look through our docs, maybe the section on disconnection in the What do you think? |
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?
Adding it to both cc @jyn514 for https://github.com/rust-lang/rust/pull/81833/files#r575693721 |
@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: |
@jyn514 Do you see the
"it's possible for more data to be sent." but I think not everyone can easily relate that as "all senders have been dropped". |
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. |
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
minor tidbits
I think it would be better if we have an example of using |
I'm not sure how that's different from what I have said, for |
I added an example based on tokio drop to show the cases we need drop. |
This comment has been minimized.
This comment has been minimized.
ping from triage: |
Yes, I have addressed the changes requested. |
@pickfire Could you squash commits into one? I'll r=josh once it's done as per #80269 (comment). |
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. Fix minor tidbits in sender recv doc Co-authored-by: Dylan DPC <dylan.dpc@gmail.com> Add example for unbounded receive loops in doc Show the drop(tx) pattern, based on tokio docs https://tokio-rs.github.io/tokio/doc/tokio/sync/index.html Fix example code for drop sender recv Fix wording in sender docs Co-authored-by: Josh Triplett <josh@joshtriplett.org>
Done |
Looks like you forgot to push it? |
Ah, thanks. I missed that. |
Thanks! @bors r=joshtriplett rollup |
Hmm, bors didn't catch it? |
@bors r=joshtriplett rollup |
📌 Commit 0f3c7d1 has been approved by |
Rollup of 10 pull requests Successful merges: - rust-lang#80269 (Explain non-dropped sender recv in docs) - rust-lang#82179 (Add functions `Duration::try_from_secs_{f32, f64}`) - rust-lang#85608 (Stabilize `ops::ControlFlow` (just the type)) - rust-lang#85792 (Refactor windows sockets impl methods) - rust-lang#86220 (Improve maybe_uninit_extra docs) - rust-lang#86277 (Remove must_use from ALLOWED_ATTRIBUTES) - rust-lang#86285 (:arrow_up: rust-analyzer) - rust-lang#86294 (Stabilize {std, core}::prelude::rust_*.) - rust-lang#86306 (Add mailmap entries for myself) - rust-lang#86314 (Remove trailing triple backticks in `mut_keyword` docs) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
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.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.