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
```