Skip to content

Commit f189cec

Browse files
elizarovqwwdfsad
elizarov
authored and
qwwdfsad
committed
Updated dispatchers references in readmes and docs
1 parent dc29b07 commit f189cec

File tree

16 files changed

+56
-53
lines changed

16 files changed

+56
-53
lines changed

‎README.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Library support for Kotlin coroutines with [multiplatform](#multiplatform) suppo
88
This is a companion version for Kotlin 1.2.61 release.
99

1010
```kotlin
11-
launch {
11+
GlobalScope.launch {
1212
delay(1000)
1313
println("Hello from Kotlin Coroutines!")
1414
}
@@ -19,14 +19,12 @@ launch {
1919
* [common](common/README.md) — common coroutines across all backends:
2020
* `launch` and `async` coroutine builders;
2121
* `Job` and `Deferred` light-weight future with cancellation support;
22-
* `delay` and `yield` top-level suspending functions.
22+
* `delay` and `yield` top-level suspending functions;
2323
* `Channel` and `Mutex` communication and synchronization primitives;
24-
* `produce` coroutine builder;
24+
* `produce` and `actor` coroutine builders;
2525
* `select` expression support and more.
2626
* [core](core/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
27-
* `CommonPool` coroutine context (default on JVM);
28-
* `actor` coroutine builder;
29-
* `IO` dispatcher for blocking coroutines
27+
* `Dispatchers.IO` dispatcher for blocking coroutines.
3028
* [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.
3129
* [native](native/README.md) — Kotlin/Native implementation of common coroutines with `runBlocking` single-threaded event loop.
3230
* [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:

‎common/kotlinx-coroutines-core-common/src/CoroutineScope.kt‎

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ import kotlin.coroutines.experimental.*
1818
*
1919
* ```
2020
* class MyActivity : AppCompatActivity(), CoroutineScope {
21-
*
21+
* lateinit var job: Job
2222
* override val coroutineContext: CoroutineContext
23-
* get() = job + UI
23+
* get() = Dispatchers.Main + job
2424
*
2525
* override fun onCreate(savedInstanceState: Bundle?) {
2626
* super.onCreate(savedInstanceState)
@@ -34,17 +34,15 @@ import kotlin.coroutines.experimental.*
3434
*
3535
* /*
3636
* * Note how coroutine builders are scoped: if activity is destroyed or any of the launched coroutines
37-
* * in this method throws an exception, then all nested coroutines will be cancelled.
37+
* * in this method throws an exception, then all nested coroutines are cancelled.
3838
* */
39-
* fun loadDataFromUI() = launch { // <- extension on current activity, launched in CommonPool
40-
* val ioData = async(IO) { // <- extension on launch scope, launched in IO dispatcher
41-
* // long computation
42-
* }
43-
*
44-
* withContext(UI) {
45-
* val data = ioData.await()
46-
* draw(data)
39+
* fun loadDataFromUI() = launch { // <- extension on current activity, launched in the main thread
40+
* val ioData = async(Dispatchers.IO) { // <- extension on launch scope, launched in IO dispatcher
41+
* // blocking I/O operation
4742
* }
43+
* // do something else concurrently with I/O
44+
* val data = ioData.await() // wait for result of I/O
45+
* draw(data) // can draw in the main thread
4846
* }
4947
* }
5048
*

‎core/kotlinx-coroutines-core/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,11 @@ Coroutine dispatchers implementing [CoroutineDispatcher]:
1616

1717
| **Name** | **Description**
1818
| --------------------------- | ---------------
19-
| [DefaultDispatcher] | Is equal to [CommonPool]
20-
| [CommonPool] | Confines coroutine execution to a shared pool of threads
19+
| [Dispatchers.Default] | Confines coroutine execution to a shared pool of background threads
20+
| [Dispatchers.Unconfined] | Does not confine coroutine execution in any way
2121
| [newSingleThreadContext] | Create new single-threaded coroutine context
2222
| [newFixedThreadPoolContext] | Creates new thread pool of a fixed size
2323
| [Executor.asCoroutineDispatcher][java.util.concurrent.Executor.asCoroutineDispatcher] | Extension to convert any executor
24-
| [Unconfined] | Does not confine coroutine execution in any way
2524

2625
More context elements:
2726

@@ -51,7 +50,7 @@ Top-level suspending functions:
5150

5251
Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
5352
helper function. [NonCancellable] job object is provided to suppress cancellation with
54-
`run(NonCancellable) {...}` block of code.
53+
`withContext(NonCancellable) {...}` block of code.
5554

5655
[Select][kotlinx.coroutines.experimental.selects.select] expression waits for the result of multiple suspending functions simultaneously:
5756

@@ -110,7 +109,8 @@ Components to ease writing unit-tests for code that contains coroutines with del
110109
[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
111110
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
112111
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
113-
[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
112+
[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
113+
[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
114114
[newSingleThreadContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-single-thread-context.html
115115
[newFixedThreadPoolContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-fixed-thread-pool-context.html
116116
[java.util.concurrent.Executor.asCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/java.util.concurrent.-executor/as-coroutine-dispatcher.html

‎core/kotlinx-coroutines-core/src/ThreadContextElement.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ public interface ThreadContextElement<S> : CoroutineContext.Element {
8484
* val myThreadLocal = ThreadLocal<String?>()
8585
* ...
8686
* println(myThreadLocal.get()) // Prints "null"
87-
* launch(CommonPool + myThreadLocal.asContextElement(value = "foo")) {
87+
* launch(Dispatchers.Default + myThreadLocal.asContextElement(value = "foo")) {
8888
* println(myThreadLocal.get()) // Prints "foo"
8989
* withContext(UI) {
9090
* println(myThreadLocal.get()) // Prints "foo", but it's on UI thread

‎core/kotlinx-coroutines-core/test/ThreadContextElementTest.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ class ThreadContextElementTest : TestBase() {
6060
expect(1)
6161
newSingleThreadContext("withContext").use {
6262
val data = MyData()
63-
GlobalScope.async(CommonPool + MyElement(data)) {
63+
GlobalScope.async(Dispatchers.Default + MyElement(data)) {
6464
assertSame(data, myThreadLocal.get())
6565
expect(2)
6666

‎core/kotlinx-coroutines-core/test/ThreadLocalTest.kt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ class ThreadLocalTest : TestBase() {
2222
@Test
2323
fun testThreadLocal() = runTest {
2424
assertNull(stringThreadLocal.get())
25-
val deferred = async(CommonPool + stringThreadLocal.asContextElement("value")) {
25+
val deferred = async(Dispatchers.Default + stringThreadLocal.asContextElement("value")) {
2626
assertEquals("value", stringThreadLocal.get())
2727
withContext(executor) {
2828
assertEquals("value", stringThreadLocal.get())
@@ -38,7 +38,7 @@ class ThreadLocalTest : TestBase() {
3838
@Test
3939
fun testThreadLocalInitialValue() = runTest {
4040
intThreadLocal.set(42)
41-
val deferred = async(CommonPool + intThreadLocal.asContextElement(239)) {
41+
val deferred = async(Dispatchers.Default + intThreadLocal.asContextElement(239)) {
4242
assertEquals(239, intThreadLocal.get())
4343
withContext(executor) {
4444
assertEquals(239, intThreadLocal.get())
@@ -55,7 +55,7 @@ class ThreadLocalTest : TestBase() {
5555
stringThreadLocal.set("test")
5656
intThreadLocal.set(314)
5757

58-
val deferred = async(CommonPool
58+
val deferred = async(Dispatchers.Default
5959
+ intThreadLocal.asContextElement(value = 239) + stringThreadLocal.asContextElement(value = "pew")) {
6060
assertEquals(239, intThreadLocal.get())
6161
assertEquals("pew", stringThreadLocal.get())
@@ -110,7 +110,7 @@ class ThreadLocalTest : TestBase() {
110110
fun testThreadLocalModification() = runTest {
111111
stringThreadLocal.set("main")
112112

113-
val deferred = async(CommonPool
113+
val deferred = async(Dispatchers.Default
114114
+ stringThreadLocal.asContextElement("initial")) {
115115
assertEquals("initial", stringThreadLocal.get())
116116

@@ -141,7 +141,7 @@ class ThreadLocalTest : TestBase() {
141141
fun testThreadLocalModificationMutableBox() = runTest {
142142
myCounterLocal.set(Counter(42))
143143

144-
val deferred = async(CommonPool
144+
val deferred = async(Dispatchers.Default
145145
+ myCounterLocal.asContextElement(Counter(0))) {
146146
assertEquals(0, myCounterLocal.get().cnt)
147147

@@ -171,7 +171,7 @@ class ThreadLocalTest : TestBase() {
171171
expect(1)
172172
newSingleThreadContext("withContext").use {
173173
val data = 42
174-
GlobalScope.async(CommonPool + intThreadLocal.asContextElement(42)) {
174+
GlobalScope.async(Dispatchers.Default + intThreadLocal.asContextElement(42)) {
175175

176176
assertSame(data, intThreadLocal.get())
177177
expect(2)

‎js/kotlinx-coroutines-core-js/README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ Coroutine dispatchers implementing [CoroutineDispatcher]:
1414

1515
| **Name** | **Description**
1616
| --------------------------- | ---------------
17-
| [DefaultDispatcher] | Posts execution to JS event loop
18-
| [Unconfined] | Does not confine coroutine execution in any way
17+
| [Dispatchers.Default] | Posts execution to JS event loop
18+
| [Dispatchers.Unconfined] | Does not confine coroutine execution in any way
1919

2020
More context elements:
2121

@@ -45,7 +45,7 @@ Top-level suspending functions:
4545

4646
Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
4747
helper function. [NonCancellable] job object is provided to suppress cancellation with
48-
`run(NonCancellable) {...}` block of code.
48+
`withContext(NonCancellable) {...}` block of code.
4949

5050
[Select][kotlinx.coroutines.experimental.selects.select] expression waits for the result of multiple suspending functions simultaneously:
5151

@@ -67,7 +67,8 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
6767
[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/async.html
6868
[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
6969
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
70-
[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
70+
[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
71+
[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
7172
[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
7273
[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
7374
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html

‎native/kotlinx-coroutines-core-native/README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ Coroutine dispatchers implementing [CoroutineDispatcher]:
1616

1717
| **Name** | **Description**
1818
| --------------------------- | ---------------
19-
| [DefaultDispatcher] | TBD
20-
| [Unconfined] | Does not confine coroutine execution in any way
19+
| [Dispatchers.Default] | References current [runBlocking] event loop
20+
| [Dispatchers.Unconfined] | Does not confine coroutine execution in any way
2121

2222
More context elements:
2323

@@ -70,7 +70,8 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
7070
[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
7171
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
7272
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
73-
[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
73+
[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
74+
[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
7475
[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
7576
[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
7677
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html

‎reactive/coroutines-guide-reactive.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -862,7 +862,7 @@ it is going to be executed in Rx computation thread pool. The output is going to
862862

863863
### Threads with coroutines
864864

865-
In the world of coroutines `Schedulers.computation()` roughly corresponds to [CommonPool],
865+
In the world of coroutines `Schedulers.computation()` roughly corresponds to [Dispatchers.Default],
866866
so the previous example is similar to the following one:
867867

868868
<!--- INCLUDE
@@ -881,7 +881,7 @@ fun rangeWithInterval(context: CoroutineContext, time: Long, start: Int, count:
881881
}
882882

883883
fun main(args: Array<String>) {
884-
Flowable.fromPublisher(rangeWithInterval(CommonPool, 100, 1, 3))
884+
Flowable.fromPublisher(rangeWithInterval(Dispatchers.Default, 100, 1, 3))
885885
.subscribe { println("$it on thread ${Thread.currentThread().name}") }
886886
Thread.sleep(1000)
887887
}
@@ -901,8 +901,8 @@ The produced output is going to be similar to:
901901

902902
Here we've used Rx
903903
[subscribe](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Flowable.html#subscribe(io.reactivex.functions.Consumer))
904-
operator that does not have its own scheduler and operates on the same thread that the publisher -- on a `CommonPool`
905-
in this example.
904+
operator that does not have its own scheduler and operates on the same thread that the publisher -- on a default
905+
shared pool of threads in this example.
906906

907907
### Rx observeOn
908908

@@ -931,7 +931,7 @@ fun rangeWithInterval(context: CoroutineContext, time: Long, start: Int, count:
931931
}
932932

933933
fun main(args: Array<String>) {
934-
Flowable.fromPublisher(rangeWithInterval(CommonPool, 100, 1, 3))
934+
Flowable.fromPublisher(rangeWithInterval(Dispatchers.Default, 100, 1, 3))
935935
.observeOn(Schedulers.computation()) // <-- THIS LINE IS ADDED
936936
.subscribe { println("$it on thread ${Thread.currentThread().name}") }
937937
Thread.sleep(1000)
@@ -1058,6 +1058,7 @@ coroutines for complex pipelines with fan-in and fan-out between multiple worker
10581058
[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
10591059
[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
10601060
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
1061+
[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
10611062
[Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/join.html
10621063
<!--- INDEX kotlinx.coroutines.experimental.channels -->
10631064
[Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel/index.html

‎reactive/kotlinx-coroutines-rx2/test/guide/example-reactive-context-02.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ fun rangeWithInterval(context: CoroutineContext, time: Long, start: Int, count:
1818
}
1919

2020
fun main(args: Array<String>) {
21-
Flowable.fromPublisher(rangeWithInterval(CommonPool, 100, 1, 3))
21+
Flowable.fromPublisher(rangeWithInterval(Dispatchers.Default, 100, 1, 3))
2222
.subscribe { println("$it on thread ${Thread.currentThread().name}") }
2323
Thread.sleep(1000)
2424
}

0 commit comments

Comments
 (0)