Skip to content

Commit 00e90dd

Browse files
elizarovelizarov
committed
MPP: Documentation (readme files)
1 parent 39ed8c6 commit 00e90dd

File tree

11 files changed

+172
-11
lines changed

11 files changed

+172
-11
lines changed

‎README.md

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,29 @@
44
[![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
55
[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=0.20) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.20)
66

7-
Library support for Kotlin coroutines.
7+
Library support for Kotlin coroutines in
8+
[Kotlin/JVM](core/README.md) and
9+
[Kotlin/JS](js/README.md).
810
This is a companion version for Kotlin 1.2.10 release.
911

12+
```kotlin
13+
launch {
14+
delay(1000)
15+
println("Hello from Kotlin Coroutine!")
16+
}
17+
```
18+
1019
## Modules
1120

12-
* [core](core/README.md) -- core primitives to work with coroutines:
13-
* `launch`, `async`, `produce`, `actor`, etc coroutine builders;
21+
* [common](common/README.md) - common coroutines across all backends:
22+
* `launch` and `async` coroutine builders;
1423
* `Job` and `Deferred` light-weight future with cancellation support;
15-
* `CommonPool` and other coroutine contexts;
24+
* `delay` and `yield` top-level suspending functions.
25+
* [js](js/README.md) - Kotlin/JS implementation of common coroutines with `Promise` support.
26+
* [core](core/README.md) -- Kotlin/JVM implementation of common coroutines with additional features:
27+
* `CommonPool` coroutine context (default on JVM);
1628
* `Channel` and `Mutex` communication and synchronization primitives;
17-
* `delay`, `yield`, etc top-level suspending functions;
29+
* `produce` and `actor` coroutine builders;
1830
* `select` expression support and more.
1931
* [reactive](reactive/README.md) -- modules that provide builders and iteration support for various reactive streams libraries:
2032
* Reactive Streams, RxJava 1.x and 2.x and Project Reactor.
@@ -80,6 +92,10 @@ buildscript {
8092
}
8193
```
8294

95+
### Kotlin/JS
96+
97+
Use `kotlinx-coroutines-core-js` artifact in your dependencies.
98+
8399
### ProGuard
84100

85101
In obfuscated code, fields with different types can have the same names,

‎common/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Common coroutines core
2+
3+
This directory contains modules that provide `expect` declarations for common coroutines support across
4+
various platforms for [mutliplatform Kotlin projects](https://kotlinlang.org/docs/reference/multiplatform.html).
5+
Note, that documentation is currently provided in platform-specific modules only.
6+
Module name below corresponds to the artifact name in Maven/Gradle.
7+
8+
## Modules
9+
10+
* [kotlinx-coroutines-core-common](kotlinx-coroutines-core-common/README.md) -- common declarations for coroutine builders and primitives.
11+

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

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Module kotlinx-coroutines-core-js
2+
3+
Common primitives to work with coroutines in
4+
[mutliplatform Kotlin projects](https://kotlinlang.org/docs/reference/multiplatform.html).
5+
6+
Note, that documentation is currently provided in platform-specific modules only:
7+
* [kotlinx-coroutines-core](../../core/kotlinx-coroutines-core/README.md) for Kotlin/JVM.
8+
* [kotlinx-coroutines-core-js](../../js/kotlinx-coroutines-core-js/README.md) for Kotlin/JS.
9+
10+
Coroutine builder functions:
11+
12+
| **Name** | **Result** | **Scope** | **Description**
13+
| ------------- | ------------- | ---------------- | ---------------
14+
| `launch` | `Job` | `CoroutineScope` | Launches coroutine that does not have any result
15+
| `async` | `Deferred` | `CoroutineScope` | Returns a single value with the future result
16+
| `runBlocking` | `T` | `CoroutineScope` | Blocks the event loop while the coroutine runs
17+
18+
Coroutine dispatchers implementing `CoroutineDispatcher`:
19+
20+
| **Name** | **Description**
21+
| --------------------------- | ---------------
22+
| `DefaultDispatcher` | Platform-specific default dispatcher
23+
| `Unconfined` | Does not confine coroutine execution in any way
24+
25+
More context elements:
26+
27+
| **Name** | **Description**
28+
| --------------------------- | ---------------
29+
| `NonCancellable` | A non-cancelable job that is always active
30+
| `CoroutineExceptionHandler` | Handler for uncaught exception
31+
32+
Top-level suspending functions:
33+
34+
| **Name** | **Description**
35+
| ------------------- | ---------------
36+
| `delay` | Non-blocking sleep
37+
| `yield` | Yields thread in single-threaded dispatchers
38+
| `withContext` | Switches to a different context
39+
| `withTimeout` | Set execution time-limit with exception on timeout
40+
| `withTimeoutOrNull` | Set execution time-limit will null result on timeout
41+
42+
Cancellation support for user-defined suspending functions is available with `suspendCancellableCoroutine`
43+
helper function. `NonCancellable` job object is provided to suppress cancellation with
44+
`run(NonCancellable) {...}` block of code.

‎core/README.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1-
# Coroutines core
1+
# Coroutines core for Kotlin/JVM
22

3-
This directory contains modules that provide core coroutine support.
3+
This directory contains modules that provide core coroutines support on Kotlin/JVM.
4+
Module name below corresponds to the artifact name in Maven/Gradle.
45

56
## Modules
67

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Module kotlinx-coroutines-core
22

3-
Core primitives to work with coroutines.
3+
Core primitives to work with coroutines on Kotlin/JVM.
44

55
Coroutine builder functions:
66

‎core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -264,6 +264,9 @@ public actual interface Job : CoroutineContext.Element {
264264

265265
// ------------ low-level state-notification ------------
266266

267+
/**
268+
* @suppress **Deprecated**: For binary compatibility
269+
*/
267270
@Deprecated(message = "For binary compatibility", level = DeprecationLevel.HIDDEN)
268271
public fun invokeOnCompletion(handler: CompletionHandler, onCancelling: Boolean): DisposableHandle
269272

‎integration/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Coroutines integration
22

3-
This directory contains modules that provide integration with various asynchronous callback- and future-based libraries:
3+
This directory contains modules that provide integration with various asynchronous callback- and future-based libraries.
4+
Module name below corresponds to the artifact name in Maven/Gradle.
45

56
## Modules
67

‎js/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Coroutines core for Kotlin/JS
2+
3+
This directory contains modules that provide core coroutines support on Kotlin/JS.
4+
Module name below corresponds to the artifact name in Maven/Gradle.
5+
6+
## Modules
7+
8+
* [kotlinx-coroutines-core-js](kotlinx-coroutines-core-js/README.md) -- core coroutine builders and primitives.
9+

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

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Module kotlinx-coroutines-core-js
2+
3+
Core primitives to work with coroutines on Kotlin/JS.
4+
5+
Coroutine builder functions:
6+
7+
| **Name** | **Result** | **Scope** | **Description**
8+
| ------------- | ------------- | ---------------- | ---------------
9+
| [launch] | [Job] | [CoroutineScope] | Launches coroutine that does not have any result
10+
| [async] | [Deferred] | [CoroutineScope] | Returns a single value with the future result
11+
| [runBlocking] | `T` | [CoroutineScope] | Blocks the event loop while the coroutine runs
12+
13+
Coroutine dispatchers implementing [CoroutineDispatcher]:
14+
15+
| **Name** | **Description**
16+
| --------------------------- | ---------------
17+
| [DefaultDispatcher] | Posts execution to JS event loop
18+
| [Unconfined] | Does not confine coroutine execution in any way
19+
20+
More context elements:
21+
22+
| **Name** | **Description**
23+
| --------------------------- | ---------------
24+
| [NonCancellable] | A non-cancelable job that is always active
25+
| [CoroutineExceptionHandler] | Handler for uncaught exception
26+
27+
Top-level suspending functions:
28+
29+
| **Name** | **Description**
30+
| ------------------- | ---------------
31+
| [delay] | Non-blocking sleep
32+
| [yield] | Yields thread in single-threaded dispatchers
33+
| [withContext] | Switches to a different context
34+
| [withTimeout] | Set execution time-limit with exception on timeout
35+
| [withTimeoutOrNull] | Set execution time-limit will null result on timeout
36+
37+
Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
38+
helper function. [NonCancellable] job object is provided to suppress cancellation with
39+
`run(NonCancellable) {...}` block of code.
40+
41+
# Package kotlinx.coroutines.experimental
42+
43+
General-purpose coroutine builders, contexts, and helper functions.
44+
45+
<!--- MODULE kotlinx-coroutines-core-js -->
46+
<!--- INDEX kotlinx.coroutines.experimental -->
47+
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
48+
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
49+
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
50+
[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/async.html
51+
[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
52+
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
53+
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
54+
[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
55+
[CommonPool]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-common-pool/index.html
56+
[newSingleThreadContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-single-thread-context.html
57+
[newFixedThreadPoolContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-fixed-thread-pool-context.html
58+
[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
59+
[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
60+
[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
61+
[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
62+
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html
63+
[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
64+
[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-context.html
65+
[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout.html
66+
[withTimeoutOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout-or-null.html
67+
[Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/join.html
68+
[Job.onJoin]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/on-join.html
69+
[Job.isCompleted]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/is-completed.html
70+
[Deferred.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/await.html
71+
[Deferred.onAwait]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/on-await.html
72+
[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
73+
[newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-coroutine-context.html
74+
<!--- END -->

‎reactive/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Coroutines for reactive streams
22

3-
This directory contains modules with utilities for various reactive stream libraries:
3+
This directory contains modules with utilities for various reactive stream libraries.
4+
Module name below corresponds to the artifact name in Maven/Gradle.
45

56
## Modules
67

0 commit comments

Comments
 (0)