Skip to content

Improve API docs #1

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

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
Open

Improve API docs #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
66ac3f4
Avoid generating documentation for `runTestCoroutine`
globsterg May 31, 2024
23173ef
Update the package descriptions in the documentation
globsterg May 31, 2024
f7d7034
Mention some additional important API entries in the top-level docs
globsterg May 31, 2024
d484a0d
Remove most of the occurrences of InternalCoroutinesApi from docs
globsterg May 31, 2024
572a89e
Update kotlinx-coroutines-core/README.md
globsterg Jul 9, 2024
486e175
Update knit refs
qwwdfsad Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 64 additions & 13 deletions kotlinx-coroutines-core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,12 @@ Coroutine builder functions:

Coroutine dispatchers implementing [CoroutineDispatcher]:

| **Name** | **Description**
| ------------------------------------------------------------------- | ---------------
| [Dispatchers.Default][kotlinx.coroutines.Dispatchers.Default] | Confines coroutine execution to a shared pool of background threads
| [Dispatchers.Unconfined][kotlinx.coroutines.Dispatchers.Unconfined] | Does not confine coroutine execution in any way
| **Name** | **Description**
| --------------------------------------------------------------------------------------------------- | ---------------
| [Dispatchers.Main][kotlinx.coroutines.Dispatchers.Main] | Confines coroutine execution to the UI thread
| [Dispatchers.Default][kotlinx.coroutines.Dispatchers.Default] | Confines coroutine execution to a shared pool of background threads
| [Dispatchers.Unconfined][kotlinx.coroutines.Dispatchers.Unconfined] | Does not confine coroutine execution in any way
| [CoroutineDispatcher.limitedParallelism][kotlinx.coroutines.CoroutineDispatcher.limitedParallelism] | Creates a view of the given dispatcher, limiting the number of tasks executing in parallel

More context elements:

Expand All @@ -27,10 +29,14 @@ More context elements:

Synchronization primitives for coroutines:

| **Name** | **Suspending functions** | **Description**
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------
| [Mutex][kotlinx.coroutines.sync.Mutex] | [lock][kotlinx.coroutines.sync.Mutex.lock] | Mutual exclusion
| [Channel][kotlinx.coroutines.channels.Channel] | [send][kotlinx.coroutines.channels.SendChannel.send], [receive][kotlinx.coroutines.channels.ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
| **Name** | **Suspending functions** | **Description**
|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| ---------------
| [Mutex][kotlinx.coroutines.sync.Mutex] | [lock][kotlinx.coroutines.sync.Mutex.lock] | Mutual exclusion
| [Semaphore][kotlinx.coroutines.sync.Semaphore] | [acquire][kotlinx.coroutines.sync.Semaphore.acquire] | Limiting the maximum concurrency
| [Channel][kotlinx.coroutines.channels.Channel] | [send][kotlinx.coroutines.channels.SendChannel.send], [receive][kotlinx.coroutines.channels.ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
| [Flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/) | [collect][kotlinx.coroutines.flow.Flow.collect] | Asynchronous stream of values

<!--- Flow direct link is here to workaround MD case-insensitivity -->

Top-level suspending functions:

Expand All @@ -45,10 +51,27 @@ Top-level suspending functions:
| [joinAll][kotlinx.coroutines.joinAll] | Joins on all given jobs

Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
helper function. [NonCancellable] job object is provided to suppress cancellation with
helper function.
The [NonCancellable] job object is provided to suppress cancellation inside the
`withContext(NonCancellable) {...}` block of code.

[Select][kotlinx.coroutines.selects.select] expression waits for the result of multiple suspending functions simultaneously:
Ways to construct asynchronous streams of values:

| **Name** | **Type** | **Description**
| --------------------------------------------------------------------- | -------- | ---------------
| [flow][kotlinx.coroutines.flow.flow] | cold | Runs a generator-style block of code that emits values
| [flowOf][kotlinx.coroutines.flow.flowOf] | cold | Emits the values passed as arguments
| [channelFlow][kotlinx.coroutines.flow.channelFlow] | cold | Runs the given code, providing a channel sending to which means emitting from the flow
| [callbackFlow][kotlinx.coroutines.flow.callbackFlow] | cold | Allows transforming a callback-based API into a flow
| [ReceiveChannel.consumeAsFlow][kotlinx.coroutines.flow.consumeAsFlow] | hot | Transforms a channel into a flow, emitting all of the received values to a single subscriber
| [ReceiveChannel.receiveAsFlow][kotlinx.coroutines.flow.receiveAsFlow] | hot | Transforms a channel into a flow, distributing the received values among its subscribers
| [MutableSharedFlow][kotlinx.coroutines.flow.MutableSharedFlow] | hot | Allows emitting each value to arbitrarily many subscribers at once
| [MutableStateFlow][kotlinx.coroutines.flow.MutableStateFlow] | hot | Represents mutable state as a flow

A *cold* stream is some process of generating values, and this process is performed separately for each subscriber.
A *hot* stream uses the same source of values independently of whether there are subscribers.

A [select][kotlinx.coroutines.selects.select] expression waits for the result of multiple suspending functions simultaneously:

| **Receiver** | **Suspending function** | **Select clause** | **Non-suspending version**
| ------------------------------------------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------
Expand All @@ -65,24 +88,36 @@ General-purpose coroutine builders, contexts, and helper functions.

# Package kotlinx.coroutines.sync

Synchronization primitives (mutex).
Synchronization primitives (mutex and semaphore).

# Package kotlinx.coroutines.channels

Channels &mdash; non-blocking primitives for communicating a stream of elements between coroutines.

# Package kotlinx.coroutines.flow

Flow &mdash; asynchronous cold stream of elements.
Flow &mdash; asynchronous cold and hot streams of elements.

# Package kotlinx.coroutines.selects

Select expression to perform multiple suspending operations simultaneously until one of them succeeds.
Select &mdash; expressions that perform multiple suspending operations simultaneously until one of them succeeds.

# Package kotlinx.coroutines.intrinsics

Low-level primitives for finer-grained control of coroutines.

# Package kotlinx.coroutines.future

[JDK 8's `CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) support.

# Package kotlinx.coroutines.stream

[JDK 8's `Stream`](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html) support.

# Package kotlinx.coroutines.time

[JDK 8's `Duration`](https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html) support via additional overloads for existing time-based operators.

<!--- MODULE kotlinx-coroutines-core -->
<!--- INDEX kotlinx.coroutines -->

Expand All @@ -93,8 +128,10 @@ Low-level primitives for finer-grained control of coroutines.
[kotlinx.coroutines.Deferred]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
[kotlinx.coroutines.runBlocking]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
[CoroutineDispatcher]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html
[kotlinx.coroutines.Dispatchers.Main]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-main.html
[kotlinx.coroutines.Dispatchers.Default]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
[kotlinx.coroutines.Dispatchers.Unconfined]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-unconfined.html
[kotlinx.coroutines.CoroutineDispatcher.limitedParallelism]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/limited-parallelism.html
[kotlinx.coroutines.NonCancellable]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-non-cancellable/index.html
[kotlinx.coroutines.CoroutineExceptionHandler]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-exception-handler/index.html
[kotlinx.coroutines.delay]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/delay.html
Expand All @@ -112,10 +149,24 @@ Low-level primitives for finer-grained control of coroutines.
[kotlinx.coroutines.Deferred.await]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/await.html
[kotlinx.coroutines.Deferred.onAwait]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/on-await.html

<!--- INDEX kotlinx.coroutines.flow -->

[kotlinx.coroutines.flow.Flow.collect]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/collect.html
[kotlinx.coroutines.flow.flow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html
[kotlinx.coroutines.flow.flowOf]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow-of.html
[kotlinx.coroutines.flow.channelFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/channel-flow.html
[kotlinx.coroutines.flow.callbackFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/callback-flow.html
[kotlinx.coroutines.flow.consumeAsFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/consume-as-flow.html
[kotlinx.coroutines.flow.receiveAsFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/receive-as-flow.html
[kotlinx.coroutines.flow.MutableSharedFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-mutable-shared-flow/index.html
[kotlinx.coroutines.flow.MutableStateFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-mutable-state-flow/index.html

<!--- INDEX kotlinx.coroutines.sync -->

[kotlinx.coroutines.sync.Mutex]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/index.html
[kotlinx.coroutines.sync.Mutex.lock]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/lock.html
[kotlinx.coroutines.sync.Semaphore]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-semaphore/index.html
[kotlinx.coroutines.sync.Semaphore.acquire]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-semaphore/acquire.html

<!--- INDEX kotlinx.coroutines.channels -->

Expand Down
8 changes: 8 additions & 0 deletions kotlinx-coroutines-core/common/src/selects/Select.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@ public sealed interface SelectBuilder<in R> {
* 4) the function that specifies how the internal result provided via
* [SelectInstance.trySelect] or [SelectInstance.selectInRegistrationPhase]
* should be processed in case of this `select` cancellation while dispatching.
*
* @suppress **This is unstable API, and it is subject to change.**
*/
@InternalCoroutinesApi
public sealed interface SelectClause {
Expand All @@ -138,6 +140,8 @@ public sealed interface SelectClause {
* the specified clause object. In case of channels, the registration logic
* coincides with the plain `send/receive` operation with the only difference that
* the `select` instance is stored as a waiter instead of continuation.
*
* @suppress **This is unstable API, and it is subject to change.**
*/
@InternalCoroutinesApi
public typealias RegistrationFunction = (clauseObject: Any, select: SelectInstance<*>, param: Any?) -> Unit
Expand All @@ -147,6 +151,8 @@ public typealias RegistrationFunction = (clauseObject: Any, select: SelectInstan
* or [SelectInstance.trySelect] should be processed. For example, both [ReceiveChannel.onReceive] and
* [ReceiveChannel.onReceiveCatching] clauses perform exactly the same synchronization logic,
* but differ when the channel has been discovered in the closed or cancelled state.
*
* @suppress **This is unstable API, and it is subject to change.**
*/
@InternalCoroutinesApi
public typealias ProcessResultFunction = (clauseObject: Any, param: Any?, clauseResult: Any?) -> Any?
Expand All @@ -156,6 +162,8 @@ public typealias ProcessResultFunction = (clauseObject: Any, param: Any?, clause
* or [SelectInstance.selectInRegistrationPhase], should be processed in case of this `select`
* cancellation while dispatching. Unfortunately, we cannot pass this function only in [SelectInstance.trySelect],
* as [SelectInstance.selectInRegistrationPhase] can be called when the coroutine is already cancelled.
*
* @suppress **This is unstable API, and it is subject to change.**
*/
@InternalCoroutinesApi
public typealias OnCancellationConstructor = (select: SelectInstance<*>, param: Any?, internalResult: Any?) ->
Expand Down
3 changes: 2 additions & 1 deletion kotlinx-coroutines-core/wasmWasi/src/internal/CoroutineRunner.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package kotlinx.coroutines.internal
import kotlinx.coroutines.*
import kotlin.coroutines.*

/** @suppress **This is internal API and it is subject to change.** */
@InternalCoroutinesApi
public fun runTestCoroutine(context: CoroutineContext, block: suspend CoroutineScope.() -> Unit) {
val newContext = GlobalScope.newCoroutineContext(context)
Expand All @@ -11,4 +12,4 @@ public fun runTestCoroutine(context: CoroutineContext, block: suspend CoroutineS
runEventLoop()
check(coroutine.isCompleted) { "Coroutine $coroutine did not complete, but the system reached quiescence" }
coroutine.getCompletionExceptionOrNull()?.let { throw it }
}
}