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

Jump to bottom

Small documentation fixes #4042

Merged
merged 6 commits into from
Feb 15, 2024
Merged

Small documentation fixes #4042

merged 6 commits into from
Feb 15, 2024

Commits on Feb 15, 2024

  1. Clarify that using runBlocking in suspend functions is allowed 

    A user raised a concern that the internal coroutines machinery may
break if `runBlocking` is used somewhere deeply in the call stack.
Calling `runBlocking` from a `suspend` functions can lead to
deadlocks naturally due to blocking the thread, or to surprising
event ordering, but nothing is expected to break.

This commit clarifies the exact danger of calling `runBlocking`
from `suspend` functions.
    @dkhalanskyjb
    dkhalanskyjb committed Feb 15, 2024
    Configuration menu
    Copy the full SHA
    fdc0818 View commit details
    Browse the repository at this point in the history

  2. Improve the explanation of how await throws exceptions 

    Fixes two issues:
* It is surprising for some users that the same exception can be
  thrown several times. Clarified this point explicitly.
* Due to #3658, `await` can throw `CancellationException` in
  several cases: when the `await` call is cancelled, or when the
  `Deferred` is cancelled. This is clarified with an example of
  how to handle this.

Fixes #3937
    @dkhalanskyjb
    dkhalanskyjb committed Feb 15, 2024
    Configuration menu
    Copy the full SHA
    8eb4963 View commit details
    Browse the repository at this point in the history

  3. Reword the prompt cancellation guarantee 

    Emphasize the fact that the function fails to resume *even if it
already completed* but wasn't dispatched yet. Before the change,
when translating the documentation to Chinese, there could be a
confusion as to what "it will not resume successfully" means.

Fixes #3888
    @dkhalanskyjb
    dkhalanskyjb committed Feb 15, 2024
    Configuration menu
    Copy the full SHA
    92df6e1 View commit details
    Browse the repository at this point in the history

  4. Don't say that job completion causes CancellationException 

    What does it even mean?
    @dkhalanskyjb
    dkhalanskyjb committed Feb 15, 2024
    Configuration menu
    Copy the full SHA
    17bae3f View commit details
    Browse the repository at this point in the history

  5. Revisit SupervisorScope, supervisorScope, and coroutineScope docs 

    Seems like a lot of the information was outdated.

Fixes #3725
    @dkhalanskyjb
    dkhalanskyjb committed Feb 15, 2024
    Configuration menu
    Copy the full SHA
    1d04452 View commit details
    Browse the repository at this point in the history

  6. Supply MDC context propagation with examples. 

    Fixes #3280
    @dkhalanskyjb
    dkhalanskyjb committed Feb 15, 2024
    Configuration menu
    Copy the full SHA
    83fa0b4 View commit details
    Browse the repository at this point in the history