sync: improve the docs for recv_many
#7201
Open
+25
−12
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Darksonn
added
T-docs
Darksonn
reviewed
Mar 7, 2025
Comment on lines
+254
to
+258
| /// * Return when the number of received messages reaches `limit`. | ||
| /// * Return earlier when the channel is closed or no further messages area | ||
| /// available in the channel at the time. In these cases, | ||
| /// the number of received messages can be lower than `limit`. | ||
| /// |
There was a problem hiding this comment.
If I'm skimming this, I'm going to see "return when the number of received messages reaches limit" and I will get the wrong impression. I agree the current docs are bad, but I don't think this wording is good either.
There was a problem hiding this comment.
Could you please give me a hint in which way the current wording isn't up to par? Otherwise I'm not sure in which direction to go with this. 😅
Trying to explain a bit better when `recv_many` will return and why in some cases the returned number of received messages is below the input parameter `limit`. Additionally the docs for the bounded and unbounded `recv_many` are adjusted to match.
SwishSwushPow
force-pushed
the
improve-docs-for-recv-many
branch
from
5674da6 to
4d665e6
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Trying to explain a bit better when
recv_manywill return and why in some cases the returned number of received messages is below the input parameterlimit.Motivation
I stumbled upon
recv_manyfor the first time ever in a bit of code while reviewing a PR. I took some issue with how the function was called (inside awhileloop) and had a look at the docs to understand why that would be necessary. When reading through the docs it seemed to me as if there was seemingly no need for a loop becauserecv_manywould apparently wait for new messages if none were available, only returning when thelimitwould be reached or the channel would be closed. I gave this a try in a smaller code example and had to realize that this was not the case. Looking at the source I found thatrecv_manywould only wait for the first message, but would return early if the channel queue had no messages available after that, even when not being closed. At this point I felt that the docs were a bit unclear in that regard.Solution
By describing the behavior a bit more explicitly I am hoping to improve the docs and avoid misunderstandings like mine in the future.