Skip to content

Commit c1a6168

Browse files
qwwdfsadqwwdfsad
committed
Restructure readme
1 parent d8d9843 commit c1a6168

File tree

7 files changed

+144
-357
lines changed

7 files changed

+144
-357
lines changed

‎README.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ GlobalScope.launch {
1919

2020
## Modules
2121

22-
* [common](kotlinx-coroutines-core/README.md) — common coroutines across all platforms:
22+
* [core](kotlinx-coroutines-core/README.md) — common coroutines across all platforms:
2323
* `launch` and `async` coroutine builders;
2424
* `Job` and `Deferred` light-weight future with cancellation support;
2525
* `MainScope` for Android and UI applications.
@@ -29,15 +29,16 @@ GlobalScope.launch {
2929
* `coroutineScope` and `supervisorScope` scope builders;
3030
* `SupervisorJob` and `CoroutineExceptionHandler` for supervision of coroutines hierarchies;
3131
* `select` expression support and more.
32-
* [core](kotlinx-coroutines-core/jvm/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
32+
* [core/jvm](kotlinx-coroutines-core/jvm/) — additional core features available on Kotlin/JVM:
3333
* `Dispatchers.IO` dispatcher for blocking coroutines;
3434
* `Executor.asCoroutineDispatcher()` extension, custom thread pools, and more.
35+
* [core/js](kotlinx-coroutines-core/js/) — additional core features available on Kotlin/JS:
36+
* Integration with `Promise`;
37+
* Integration with `Window`.
3538
* [test](kotlinx-coroutines-test/README.md) — test utilities for coroutines
3639
* `Dispatchers.setMain` to override `Dispatchers.Main` in tests.
3740
* [debug](kotlinx-coroutines-debug/README.md) — debug utilities for coroutines.
3841
* `DebugProbes` API to probe, keep track of, print and dump active coroutines.
39-
* [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.
40-
* [native](native/README.md) — Kotlin/Native implementation of common coroutines with `runBlocking` single-threaded event loop.
4142
* [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:
4243
* Reactive Streams, RxJava 2.x, and Project Reactor.
4344
* [ui](ui/README.md) — modules that provide coroutine dispatchers for various single-threaded UI libraries:

‎docs/channels.md

+1
Original file line numberDiff line numberDiff line change
@@ -701,6 +701,7 @@ delay between elements.
701701
<!--- INDEX kotlinx.coroutines -->
702702
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
703703
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
704+
[kotlin.coroutines.CoroutineContext.cancelChildren]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/kotlin.coroutines.-coroutine-context/cancel-children.html
704705
[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
705706
<!--- INDEX kotlinx.coroutines.channels -->
706707
[Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/index.html

‎js/README.md

+2-16
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,4 @@
1-
# Coroutines core for Kotlin/JS
1+
# Example of Kotlin JS application with coroutines
22

3-
This directory contains modules that provide core coroutines support on Kotlin/JS.
4-
5-
## Using in your projects
6-
7-
Use [`org.jetbrains.kotlinx:kotlinx-coroutines-core-js:<version>`](kotlinx-coroutines-core-js/README.md)
8-
module in your Gradle/Maven dependencies
9-
or install [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) package via NPM.
10-
11-
Since Kotlin/JS does not generally provide binary compatibility between versions,
12-
you should use the same version of Kotlin compiler as was used to build `kotlinx.coroutines`.
13-
See [gradle.properties](../gradle.properties).
14-
15-
## Examples
16-
17-
* [example-frontend-js](example-frontend-js/README.md) -- frontend application written in Kotlin/JS
3+
[example-frontend-js](example-frontend-js/README.md) -- frontend application written in Kotlin/JS
184
that uses coroutines to implement animations in imperative style.

‎kotlinx-coroutines-core/README.md

+136-7
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,140 @@
1-
# Coroutines core for Kotlin/JVM
1+
# Module kotlinx-coroutines-core
22

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.
3+
Core primitives to work with coroutines, available on all platforms.
54

6-
## Modules
5+
Coroutine builder functions:
76

8-
* [kotlinx-coroutines-core](kotlinx-coroutines-core/README.md) &mdash; core coroutine builders and synchronization primitives.
9-
* [kotlinx-coroutines-debug](kotlinx-coroutines-debug/README.md) &mdash; coroutines debug utilities.
10-
* [kotlinx-coroutines-test](kotlinx-coroutines-test/README.md) &mdash; coroutines test utilities.
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+
| [produce][kotlinx.coroutines.channels.produce] | [ReceiveChannel][kotlinx.coroutines.channels.ReceiveChannel] | [ProducerScope][kotlinx.coroutines.channels.ProducerScope] | Produces a stream of elements
12+
| [runBlocking] | `T` | [CoroutineScope] | Blocks the thread while the coroutine runs
1113

14+
Coroutine dispatchers implementing [CoroutineDispatcher]:
15+
16+
| **Name** | **Description**
17+
| --------------------------- | ---------------
18+
| [Dispatchers.Default] | Confines coroutine execution to a shared pool of background threads
19+
| [Dispatchers.Unconfined] | Does not confine coroutine execution in any way
20+
21+
More context elements:
22+
23+
| **Name** | **Description**
24+
| --------------------------- | ---------------
25+
| [NonCancellable] | A non-cancelable job that is always active
26+
| [CoroutineExceptionHandler] | Handler for uncaught exception
27+
28+
Synchronization primitives for coroutines:
29+
30+
| **Name** | **Suspending functions** | **Description**
31+
| ---------- | ----------------------------------------------------------- | ---------------
32+
| [Mutex][kotlinx.coroutines.sync.Mutex] | [lock][kotlinx.coroutines.sync.Mutex.lock] | Mutual exclusion
33+
| [Channel][kotlinx.coroutines.channels.Channel] | [send][kotlinx.coroutines.channels.SendChannel.send], [receive][kotlinx.coroutines.channels.ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
34+
35+
Top-level suspending functions:
36+
37+
| **Name** | **Description**
38+
| ------------------- | ---------------
39+
| [delay] | Non-blocking sleep
40+
| [yield] | Yields thread in single-threaded dispatchers
41+
| [withContext] | Switches to a different context
42+
| [withTimeout] | Set execution time-limit with exception on timeout
43+
| [withTimeoutOrNull] | Set execution time-limit will null result on timeout
44+
| [awaitAll] | Awaits for successful completion of all given jobs or exceptional completion of any
45+
| [joinAll] | Joins on all given jobs
46+
47+
Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
48+
helper function. [NonCancellable] job object is provided to suppress cancellation with
49+
`withContext(NonCancellable) {...}` block of code.
50+
51+
[Select][kotlinx.coroutines.selects.select] expression waits for the result of multiple suspending functions simultaneously:
52+
53+
| **Receiver** | **Suspending function** | **Select clause** | **Non-suspending version**
54+
| ---------------- | --------------------------------------------- | ------------------------------------------------ | --------------------------
55+
| [Job] | [join][Job.join] | [onJoin][Job.onJoin] | [isCompleted][Job.isCompleted]
56+
| [Deferred] | [await][Deferred.await] | [onAwait][Deferred.onAwait] | [isCompleted][Job.isCompleted]
57+
| [SendChannel][kotlinx.coroutines.channels.SendChannel] | [send][kotlinx.coroutines.channels.SendChannel.send] | [onSend][kotlinx.coroutines.channels.SendChannel.onSend] | [offer][kotlinx.coroutines.channels.SendChannel.offer]
58+
| [ReceiveChannel][kotlinx.coroutines.channels.ReceiveChannel] | [receive][kotlinx.coroutines.channels.ReceiveChannel.receive] | [onReceive][kotlinx.coroutines.channels.ReceiveChannel.onReceive] | [poll][kotlinx.coroutines.channels.ReceiveChannel.poll]
59+
| [ReceiveChannel][kotlinx.coroutines.channels.ReceiveChannel] | [receiveOrNull][kotlinx.coroutines.channels.ReceiveChannel.receiveOrNull] | [onReceiveOrNull][kotlinx.coroutines.channels.ReceiveChannel.onReceiveOrNull] | [poll][kotlinx.coroutines.channels.ReceiveChannel.poll]
60+
| [Mutex][kotlinx.coroutines.sync.Mutex] | [lock][kotlinx.coroutines.sync.Mutex.lock] | [onLock][kotlinx.coroutines.sync.Mutex.onLock] | [tryLock][kotlinx.coroutines.sync.Mutex.tryLock]
61+
| none | [delay] | [onTimeout][kotlinx.coroutines.selects.SelectBuilder.onTimeout] | none
62+
63+
# Package kotlinx.coroutines
64+
65+
General-purpose coroutine builders, contexts, and helper functions.
66+
67+
# Package kotlinx.coroutines.sync
68+
69+
Synchronization primitives (mutex).
70+
71+
# Package kotlinx.coroutines.channels
72+
73+
Channels -- non-blocking primitives for communicating a stream of elements between coroutines.
74+
75+
# Package kotlinx.coroutines.selects
76+
77+
Select expression to perform multiple suspending operations simultaneously until one of them succeeds.
78+
79+
# Package kotlinx.coroutines.intrinsics
80+
81+
Low-level primitives for finer-grained control of coroutines.
82+
83+
# Package kotlinx.coroutines.timeunit
84+
85+
Optional time unit support for multiplatform projects.
86+
87+
# Package kotlinx.coroutines.test
88+
89+
Components to ease writing unit-tests for code that contains coroutines with delays and timeouts.
90+
91+
<!--- MODULE kotlinx-coroutines-core -->
92+
<!--- INDEX kotlinx.coroutines -->
93+
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html
94+
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
95+
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
96+
[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html
97+
[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
98+
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
99+
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html
100+
[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
101+
[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-unconfined.html
102+
[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-non-cancellable.html
103+
[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-exception-handler/index.html
104+
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/delay.html
105+
[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/yield.html
106+
[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-context.html
107+
[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout.html
108+
[withTimeoutOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout-or-null.html
109+
[awaitAll]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/await-all.html
110+
[joinAll]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/join-all.html
111+
[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/suspend-cancellable-coroutine.html
112+
[Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/join.html
113+
[Job.onJoin]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/on-join.html
114+
[Job.isCompleted]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/is-completed.html
115+
[Deferred.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/await.html
116+
[Deferred.onAwait]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/on-await.html
117+
<!--- INDEX kotlinx.coroutines.sync -->
118+
[kotlinx.coroutines.sync.Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/index.html
119+
[kotlinx.coroutines.sync.Mutex.lock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/lock.html
120+
[kotlinx.coroutines.sync.Mutex.onLock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/on-lock.html
121+
[kotlinx.coroutines.sync.Mutex.tryLock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/try-lock.html
122+
<!--- INDEX kotlinx.coroutines.channels -->
123+
[kotlinx.coroutines.channels.produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/produce.html
124+
[kotlinx.coroutines.channels.ReceiveChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-receive-channel/index.html
125+
[kotlinx.coroutines.channels.ProducerScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-producer-scope/index.html
126+
[kotlinx.coroutines.channels.Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/index.html
127+
[kotlinx.coroutines.channels.SendChannel.send]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/send.html
128+
[kotlinx.coroutines.channels.ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-receive-channel/receive.html
129+
[kotlinx.coroutines.channels.SendChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/index.html
130+
[kotlinx.coroutines.channels.SendChannel.onSend]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/on-send.html
131+
[kotlinx.coroutines.channels.SendChannel.offer]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/offer.html
132+
[kotlinx.coroutines.channels.ReceiveChannel.onReceive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-receive-channel/on-receive.html
133+
[kotlinx.coroutines.channels.ReceiveChannel.poll]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-receive-channel/poll.html
134+
[kotlinx.coroutines.channels.ReceiveChannel.receiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-receive-channel/receive-or-null.html
135+
[kotlinx.coroutines.channels.ReceiveChannel.onReceiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-receive-channel/on-receive-or-null.html
136+
<!--- INDEX kotlinx.coroutines.selects -->
137+
[kotlinx.coroutines.selects.select]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.selects/select.html
138+
[kotlinx.coroutines.selects.SelectBuilder.onTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.selects/-select-builder/on-timeout.html
139+
<!--- INDEX kotlinx.coroutines.test -->
140+
<!--- END -->

0 commit comments

Comments
 (0)