Skip to content
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.

Sign up for GitHub

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

Improve documentation for select!{} #6572

Closed
wants to merge 1 commit into from
Closed

Improve documentation for select!{} #6572

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions tokio/src/macros/select.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,13 @@ macro_rules! doc {
/// 2. Aggregate the `<async expression>`s from each branch, including the
/// disabled ones. If the branch is disabled, `<async expression>` is still
/// evaluated, but the resulting future is not polled.
/// 3. Concurrently await on the results for all remaining `<async expression>`s.
/// 4. Once an `<async expression>` returns a value, attempt to apply the value
/// 3. If **all** branches are disabled: evaluate the `else` expression if one is provided
/// and return, otherwise panic.
/// 4. Concurrently await on the results for all remaining enabled `<async expression>`s.
/// 5. Once an `<async expression>` returns a value, attempt to apply the value
/// to the provided `<pattern>`, if the pattern matches, evaluate `<handler>`
/// and return. If the pattern **does not** match, disable the current branch
/// and for the remainder of the current call to `select!`. Continue from step 3.
Comment on lines +45 to 48
Copy link
Contributor

@Darksonn Darksonn May 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Branches become disabled if the pattern doesn't match, which can in turn trigger the else branch. So it makes more sense to me to have the else branch below this.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The else branch can also be triggered before anything is polled if all the expressions are disabled via their condition, or if there are no expressions to begin with.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could perhaps list it twice, but I don't think it makes sense to remove the mention of else at the end.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At present, step 5 about else is never reached by following the lifecycle as written. Do you have any suggestions for rewording it to make it more correct?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can say "if all branches are disabled, go to step 6" and keep the step at the end?

/// 5. If **all** branches are disabled, evaluate the `else` expression. If no
/// else branch is provided, panic.
///
/// # Runtime characteristics
///
Expand Down
Loading