Deprecate awaitSingleOr*, specialize some await* functions for Mono and Maybe #2628
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
qwwdfsad
requested changes
Apr 6, 2021
dkhalanskyjb
changed the title
Closed
qwwdfsad
reviewed
Apr 19, 2021
| message = "Deprecated without a replacement due to its name incorrectly conveying the behavior. " + | ||
| "Please consider using awaitFirstOrDefault().", | ||
| level = DeprecationLevel.WARNING | ||
| ) | ||
| public suspend fun <T> Publisher<T>.awaitSingleOrDefault(default: T): T = awaitOne(Mode.SINGLE_OR_DEFAULT, default) |
There was a problem hiding this comment.
Two things regarding deprecation:
- It's worth adding
### Deprecationsection to KDoc with an explanation of why this function is deprecated and, if necessary, why there is no built-in replacement. The rest of KDoc can be removed, but not hard opinion here. - To simplify maintenance and user's view of deprecation timeline, we add a short note about it:
@Deprecated(
message = "Deprecated without a replacement due to its name incorrectly conveying the behavior. " +
"Please consider using awaitFirstOrDefault().",
level = DeprecationLevel.WARNING
) // Warning since 1.5, error in 1.6, hidden in 1.7
|
|
||
| override fun onComplete() { | ||
| if (!seenValue) | ||
| cont.resume(null) |
There was a problem hiding this comment.
[nit] I'd suggest sticking to either one-liners or using explicit scoping with {}
qwwdfsad
approved these changes
Apr 20, 2021
| */ | ||
| @Deprecated( | ||
| message = "Mono produces at most one value, so the semantics of dropping the remaining elements are not useful. " + | ||
| "Please use awaitSingle() instead.", | ||
| level = DeprecationLevel.WARNING, | ||
| replaceWith = ReplaceWith("this.awaitSingle()") | ||
| ) | ||
| ) // Warning since 1.5, error in 1.6, hidden in 1.7 |
There was a problem hiding this comment.
It won't be hidden because this is added as a lint hint, otherwise, it wouldn't be added in the first place
| * function immediately cancels its [Subscription] and resumes with [CancellationException]. | ||
| * | ||
| * @throws NoSuchElementException if the publisher does not emit any value | ||
| * This function is deprecated in favor of [Mono.awaitSingle]. |
There was a problem hiding this comment.
This phrasing implicitly implies that this function was non-deprecated prior to this version.
I suggest rephrasing it more explicitly, e.g.: "This is a deprecated lint function to improve user experience and guard against ambiguous Mono usages." and adding example to the end of KDoc:
Example of ambiguous usage:
\```
// The signature of the call suggests that one or zero values can be returned from 'findById', but 'awaitFirstOrNull' instead of 'awaitSingleOrNull' may trick the reader into believing that more than one value can be returned
myDbClient.findById(uniqueId).awaitFirstOrNull()
\```
There was a problem hiding this comment.
Changed. What do you think?
pablobaxter
pushed a commit
to pablobaxter/kotlinx.coroutines
that referenced
this pull request
Sep 14, 2022
…nd Maybe (Kotlin#2628) * Deprecated `awaitSingleOr*` on arbitrary Publishers * Added specialized `awaitSingle` and `awaitSingleOrNull` methods on `Maybe<T>` and `Mono<T>` * Deprecated `Maybe<T>.await()` in favor of `Maybe<T>.awaitSingleOrNull()` * Added specializations of most of the `await*` methods for `Mono<T>` and deprecated them, as the only useful methods on `Mono<T>` are `awaitSingle` and `awaitSingleOrNull` * Reworded some documentation for `await*` methods Fixes Kotlin#2591 Fixes Kotlin#1587
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.
This PR
awaitSingleOr*on arbitrary PublishersawaitSingleandawaitSingleOrNullmethods onMaybe<T>andMono<T>Maybe<T>.await()in favor ofMaybe<T>.awaitSingleOrNull()await*methods forMono<T>and deprecates them, as the only useful methods onMono<T>areawaitSingleandawaitSingleOrNullawait*methodsFixes #2591
Fixes #1587