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

Update docs about creating custom CoroutineScopes #3306

Merged
merged 1 commit into from May 30, 2022
Merged

Update docs about creating custom CoroutineScopes #3306

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.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
12 changes: 6 additions & 6 deletions kotlinx-coroutines-core/common/src/CoroutineScope.kt
View file
Open in desktop
Expand Up @@ -42,14 +42,14 @@ import kotlin.coroutines.intrinsics.*
* ### Custom usage
*
* `CoroutineScope` should be declared as a property on entities with a well-defined lifecycle that are
* responsible for launching children coroutines. The corresponding instance of `CoroutineScope` shall be created
* with either `CoroutineScope()` or `MainScope()` functions. The difference between them is only in the
* [CoroutineDispatcher]:
* responsible for launching child coroutines. The corresponding instance of `CoroutineScope` shall be created
* with either `CoroutineScope()` or `MainScope()`:
*
* * `CoroutineScope()` uses [Dispatchers.Default] for its coroutines.
* * `MainScope()` uses [Dispatchers.Main] for its coroutines.
* * `CoroutineScope()` uses the [context][CoroutineContext] provided to it as a parameter for its coroutines
* and adds a [Job] if one is not provided as part of the context.
Copy link
Collaborator

Choose a reason for hiding this comment

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

The part about Dispatchers.Default is important though. If one knows that Dispatchers.Default is used by default, yes, it's obvious what happens when a dispatcher is not specified, but if one does not, it's unclear where to look.

Copy link
Member

@qwwdfsad qwwdfsad May 30, 2022 •
edited

Choose a reason for hiding this comment

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

Every coroutine builder mentions Dispatchers.Default though:

If the context does not have any dispatcher or other [ContinuationInterceptor], then [Dispatchers.Default] is used.
The parent job is inherited from the [CoroutineScope] as well, but it can also be overridden
with a corresponding [context] element.

And mentioning Dispatchers.Default here is just being incorrect -- CoroutineScope() does not provide any dispatcher and each coroutine decides what to use on its own. E.g. some may use Dispatches.Unconfined when the dispatcher is not supplied

Copy link
Collaborator

Choose a reason for hiding this comment

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

Ah, ok, didn't notice launch mentioning Dispatchers.Default.

* * `MainScope()` uses [Dispatchers.Main] for its coroutines and has a [SupervisorJob].
*
* **The key part of custom usage of `CustomScope` is cancelling it at the end of the lifecycle.**
* **The key part of custom usage of `CoroutineScope` is cancelling it at the end of the lifecycle.**
* The [CoroutineScope.cancel] extension function shall be used when the entity that was launching coroutines
* is no longer needed. It cancels all the coroutines that might still be running on behalf of it.
*
Expand Down