0
# kotlinx-coroutines-core-jvm
1
2
The JVM-specific implementation of kotlinx.coroutines library providing comprehensive support for asynchronous programming in Kotlin. This library offers coroutine primitives, builders, dispatchers, and synchronization mechanisms for concurrent programming with structured concurrency, cancellation support, and reactive streams through Flow API.
3
4
## Package Information
5
6
- **Package Name**: org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**:
10
```kotlin
11
dependencies {
12
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.10.2")
13
}
14
```
15
16
## Core Imports
17
18
```kotlin
19
import kotlinx.coroutines.*
20
```
21
22
For specific components:
23
24
```kotlin
25
import kotlinx.coroutines.flow.*
26
import kotlinx.coroutines.channels.*
27
import kotlinx.coroutines.sync.*
28
```
29
30
## Basic Usage
31
32
```kotlin
33
import kotlinx.coroutines.*
34
35
fun main() = runBlocking {
36
// Launch a coroutine
37
val job = launch {
38
delay(1000L)
39
println("Coroutine completed!")
40
}
41
42
// Create async computation
43
val deferred = async {
44
delay(500L)
45
"Hello from async"
46
}
47
48
// Wait for results
49
val result = deferred.await()
50
println(result)
51
job.join()
52
}
53
54
// Using different dispatchers
55
fun example() = runBlocking {
56
withContext(Dispatchers.IO) {
57
// Blocking I/O operation
58
performBlockingIO()
59
}
60
61
withContext(Dispatchers.Default) {
62
// CPU-intensive computation
63
performComputation()
64
}
65
}
66
```
67
68
## Architecture
69
70
kotlinx-coroutines is built around several key architectural concepts:
71
72
- **Structured Concurrency**: Coroutines are organized in hierarchical scopes ensuring proper cancellation and resource cleanup
73
- **Context Preservation**: Coroutine context elements (dispatcher, job, exception handler) are preserved across suspension points
74
- **Cancellation Cooperation**: Built-in cancellation mechanism that propagates through coroutine hierarchies
75
- **Dispatchers**: Thread pool abstractions for different execution contexts (Default, IO, Main, Unconfined)
76
- **Suspending Functions**: Non-blocking functions that can be paused and resumed without blocking threads
77
- **Cold Flows**: Asynchronous sequences with backpressure and exception transparency
78
- **Hot Flows**: Shared state and event streams (SharedFlow, StateFlow) for reactive programming
79
80
## Capabilities
81
82
### Coroutine Builders
83
84
Core functions for creating and launching coroutines with different execution patterns and lifecycle management.
85
86
```kotlin { .api }
87
fun CoroutineScope.launch(
88
context: CoroutineContext = EmptyCoroutineContext,
89
start: CoroutineStart = CoroutineStart.DEFAULT,
90
block: suspend CoroutineScope.() -> Unit
91
): Job
92
93
fun <T> CoroutineScope.async(
94
context: CoroutineContext = EmptyCoroutineContext,
95
start: CoroutineStart = CoroutineStart.DEFAULT,
96
block: suspend CoroutineScope.() -> T
97
): Deferred<T>
98
99
suspend fun <T> withContext(
100
context: CoroutineContext,
101
block: suspend CoroutineScope.() -> T
102
): T
103
104
fun <T> runBlocking(
105
context: CoroutineContext = EmptyCoroutineContext,
106
block: suspend CoroutineScope.() -> T
107
): T
108
```
109
110
[Coroutine Builders](./coroutine-builders.md)
111
112
### Dispatchers
113
114
Thread pool implementations for different execution contexts, with JVM-specific optimizations for IO operations and CPU-intensive tasks.
115
116
```kotlin { .api }
117
object Dispatchers {
118
val Default: CoroutineDispatcher
119
val Main: MainCoroutineDispatcher
120
val IO: CoroutineDispatcher
121
val Unconfined: CoroutineDispatcher
122
123
@DelicateCoroutinesApi
124
fun shutdown()
125
}
126
```
127
128
[Dispatchers](./dispatchers.md)
129
130
### Job Management
131
132
Lifecycle management for coroutines with hierarchical cancellation, completion tracking, and structured concurrency support.
133
134
```kotlin { .api }
135
interface Job : CoroutineContext.Element {
136
val isActive: Boolean
137
val isCompleted: Boolean
138
val isCancelled: Boolean
139
val children: Sequence<Job>
140
141
fun start(): Boolean
142
fun cancel(cause: CancellationException? = null)
143
suspend fun join()
144
val onJoin: SelectClause0
145
fun invokeOnCompletion(handler: CompletionHandler): DisposableHandle
146
}
147
148
interface Deferred<out T> : Job {
149
suspend fun await(): T
150
val onAwait: SelectClause1<T>
151
fun getCompleted(): T
152
fun getCompletionExceptionOrNull(): Throwable?
153
}
154
```
155
156
[Job Management](./job-management.md)
157
158
### Flow API
159
160
Reactive streams implementation with cold flows for asynchronous sequences and hot flows for shared state management.
161
162
```kotlin { .api }
163
interface Flow<out T> {
164
suspend fun collect(collector: FlowCollector<T>)
165
}
166
167
interface FlowCollector<in T> {
168
suspend fun emit(value: T)
169
}
170
171
interface SharedFlow<out T> : Flow<T> {
172
val replayCache: List<T>
173
val subscriptionCount: StateFlow<Int>
174
}
175
176
interface StateFlow<out T> : SharedFlow<T> {
177
val value: T
178
}
179
```
180
181
[Flow API](./flow-api.md)
182
183
### Channels
184
185
Message passing primitives for communication between coroutines with various capacity and buffering strategies.
186
187
```kotlin { .api }
188
interface Channel<E> : SendChannel<E>, ReceiveChannel<E>
189
190
interface SendChannel<in E> {
191
suspend fun send(element: E)
192
fun trySend(element: E): ChannelResult<Unit>
193
fun close(cause: Throwable? = null): Boolean
194
}
195
196
interface ReceiveChannel<out E> {
197
suspend fun receive(): E
198
fun tryReceive(): ChannelResult<E>
199
suspend fun receiveCatching(): ChannelResult<E>
200
}
201
```
202
203
[Channels](./channels.md)
204
205
### Synchronization Primitives
206
207
Thread-safe synchronization mechanisms designed for coroutines including mutexes, semaphores, and atomic operations.
208
209
```kotlin { .api }
210
interface Mutex {
211
val isLocked: Boolean
212
suspend fun lock(owner: Any? = null)
213
fun tryLock(owner: Any? = null): Boolean
214
fun unlock(owner: Any? = null)
215
}
216
217
interface Semaphore {
218
val availablePermits: Int
219
suspend fun acquire()
220
fun tryAcquire(): Boolean
221
fun release()
222
}
223
```
224
225
[Synchronization](./synchronization.md)
226
227
### Exception Handling
228
229
Structured exception handling with coroutine-aware propagation, cancellation semantics, and supervisor patterns.
230
231
```kotlin { .api }
232
interface CoroutineExceptionHandler : CoroutineContext.Element {
233
fun handleException(context: CoroutineContext, exception: Throwable)
234
}
235
236
fun SupervisorJob(parent: Job? = null): CompletableJob
237
238
suspend fun <T> supervisorScope(
239
block: suspend CoroutineScope.() -> T
240
): T
241
```
242
243
[Exception Handling](./exception-handling.md)
244
245
### JVM Integration
246
247
Platform-specific features for JVM including executor integration, CompletableFuture interoperability, and thread-local context elements.
248
249
```kotlin { .api }
250
fun Executor.asCoroutineDispatcher(): ExecutorCoroutineDispatcher
251
252
fun <T> CompletableFuture<T>.asDeferred(): Deferred<T>
253
suspend fun <T> CompletableFuture<T>.await(): T
254
255
fun <T> ThreadLocal<T>.asContextElement(value: T): ThreadContextElement<T>
256
```
257
258
[JVM Integration](./jvm-integration.md)
259
260
## Types
261
262
```kotlin { .api }
263
/** Select clause interfaces for coroutine select expressions */
264
sealed interface SelectClause0
265
sealed interface SelectClause1<out T>
266
sealed interface SelectClause2<in P, out Q>
267
268
/** Completion handler type alias */
269
typealias CompletionHandler = (cause: Throwable?) -> Unit
270
```