README.md

Module kotlinx-coroutines-core

Core primitives to work with coroutines.

Coroutine builder functions:

Name	Result	Scope	Description
launch	Job	CoroutineScope	Launches coroutine that does not have any result
async	Deferred	CoroutineScope	Returns a single value with the future result
produce	ReceiveChannel	ProducerScope	Produces a stream of elements
runBlocking	T	CoroutineScope	Blocks the thread while the coroutine runs

Coroutine dispatchers implementing CoroutineDispatcher:

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

More context elements:

Name	Description
NonCancellable	A non-cancelable job that is always active
CoroutineExceptionHandler	Handler for uncaught exception

Synchronization primitives for coroutines:

Name	Suspending functions	Description
Mutex	lock	Mutual exclusion
Semaphore	acquire	Limiting the maximum concurrency
Channel	send, receive	Communication channel (aka queue or exchanger)
Flow	collect	Asynchronous stream of values

Top-level suspending functions:

Name	Description
delay	Non-blocking sleep
yield	Yields thread in single-threaded dispatchers
withContext	Switches to a different context
withTimeout	Set execution time-limit with exception on timeout
withTimeoutOrNull	Set execution time-limit will null result on timeout
awaitAll	Awaits for successful completion of all given jobs or exceptional completion of any
joinAll	Joins on all given jobs

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

Ways to construct asynchronous streams of values:

Name	Type	Description
flow	cold	Runs a generator-style block of code that emits values
flowOf	cold	Emits the values passed as arguments
channelFlow	cold	Runs the given code, providing a channel sending to which means emitting from the flow
callbackFlow	cold	Allows transforming a callback-based API into a flow
ReceiveChannel.consumeAsFlow	hot	Transforms a channel into a flow, emitting all of the received values to a single subscriber
ReceiveChannel.receiveAsFlow	hot	Transforms a channel into a flow, distributing the received values among its subscribers
MutableSharedFlow	hot	Allows emitting each value to arbitrarily many subscribers at once
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 expression waits for the result of multiple suspending functions simultaneously:

Receiver	Suspending function	Select clause	Non-suspending version
Job	join	onJoin	isCompleted
Deferred	await	onAwait	isCompleted
SendChannel	send	onSend	trySend
ReceiveChannel	receive	onReceive	tryReceive
ReceiveChannel	receiveCatching	onReceiveCatching	tryReceive
none	delay	onTimeout	none

Package kotlinx.coroutines

General-purpose coroutine builders, contexts, and helper functions.

Package kotlinx.coroutines.sync

Synchronization primitives (mutex and semaphore).

Package kotlinx.coroutines.channels

Channels — non-blocking primitives for communicating a stream of elements between coroutines.

Package kotlinx.coroutines.flow

Flow — asynchronous cold and hot streams of elements.

Package kotlinx.coroutines.selects

Select — 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 support.

Package kotlinx.coroutines.stream

JDK 8's Stream support.

Package kotlinx.coroutines.time

JDK 8's Duration support via additional overloads for existing time-based operators.