0
# AtomicFU JVM
1

2
AtomicFU is a multiplatform Kotlin library providing idiomatic and efficient atomic operations. The JVM-specific artifact transforms atomic operations into highly optimized bytecode using AtomicXxxFieldUpdater or VarHandle for maximum performance, ensuring zero runtime overhead while maintaining a clean, Kotlin-idiomatic API.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlinx:atomicfu-jvm
7
- **Package Type**: maven (Gradle/Maven)
8
- **Language**: Kotlin
9
- **Installation**: 
10
  - Gradle: `implementation("org.jetbrains.kotlinx:atomicfu-jvm:0.29.0")`
11
  - Maven: `<dependency><groupId>org.jetbrains.kotlinx</groupId><artifactId>atomicfu-jvm</artifactId><version>0.29.0</version></dependency>`
12

13
## Core Imports
14

15
```kotlin
16
import kotlinx.atomicfu.*
17
```
18

19
For specific functionality:
20

21
```kotlin
22
import kotlinx.atomicfu.atomic
23
import kotlinx.atomicfu.AtomicRef
24
import kotlinx.atomicfu.AtomicInt
25
import kotlinx.atomicfu.AtomicLong
26
import kotlinx.atomicfu.AtomicBoolean
27
```
28

29
For locks and synchronization:
30

31
```kotlin
32
import kotlinx.atomicfu.locks.*
33
```
34

35
For tracing:
36

37
```kotlin
38
import kotlinx.atomicfu.Trace
39
import kotlinx.atomicfu.TraceBase
40
```
41

42
## Basic Usage
43

44
```kotlin
45
import kotlinx.atomicfu.*
46

47
class Counter {
48
    // Atomic fields must be private read-only properties
49
    private val count = atomic(0)
50
    private val name = atomic<String?>(null)
51
    
52
    fun increment(): Int = count.incrementAndGet()
53
    
54
    fun getName(): String? = name.value
55
    
56
    fun setName(newName: String) {
57
        name.value = newName
58
    }
59
    
60
    fun compareAndSwapName(expected: String?, newName: String): Boolean =
61
        name.compareAndSet(expected, newName)
62
}
63

64
// Usage
65
val counter = Counter()
66
println(counter.increment()) // 1
67
println(counter.increment()) // 2
68

69
counter.setName("MyCounter")
70
println(counter.getName()) // "MyCounter"
71
```
72

73
## Architecture
74

75
AtomicFU is built around several key components:
76

77
- **Compile-time Transformation**: High-level atomic API calls are transformed into platform-optimized implementations during compilation
78
- **Field Updaters**: On JVM, uses AtomicXxxFieldUpdater for compatibility or VarHandle for Java 9+ performance
79
- **Zero Runtime Overhead**: All transformations happen at compile time, resulting in optimal bytecode
80
- **Type Safety**: Full Kotlin type system integration with atomic operations
81
- **Tracing Support**: Optional debugging and monitoring capabilities for atomic operations
82
- **Lock Integration**: Multiplatform synchronization primitives for advanced use cases
83

84
## Capabilities
85

86
### Atomic Operations
87

88
Core atomic variables and operations for thread-safe programming with automatic compile-time optimization.
89

90
```kotlin { .api }
91
fun <T> atomic(initial: T): AtomicRef<T>
92
fun <T> atomic(initial: T, trace: TraceBase): AtomicRef<T>
93
fun atomic(initial: Int): AtomicInt
94
fun atomic(initial: Int, trace: TraceBase): AtomicInt
95
fun atomic(initial: Long): AtomicLong
96
fun atomic(initial: Long, trace: TraceBase): AtomicLong
97
fun atomic(initial: Boolean): AtomicBoolean
98
fun atomic(initial: Boolean, trace: TraceBase): AtomicBoolean
99
```
100

101
[Atomic Operations](./atomic-operations.md)
102

103
### Atomic Arrays
104

105
Array-based atomic data structures for managing collections of atomic values.
106

107
```kotlin { .api }
108
fun <T> atomicArrayOfNulls(size: Int): AtomicArray<T?>
109

110
class AtomicIntArray(size: Int) {
111
    val size: Int
112
    operator fun get(index: Int): AtomicInt
113
}
114

115
class AtomicLongArray(size: Int) {
116
    val size: Int
117
    operator fun get(index: Int): AtomicLong
118
}
119

120
class AtomicBooleanArray(size: Int) {
121
    val size: Int
122
    operator fun get(index: Int): AtomicBoolean
123
}
124
```
125

126
[Atomic Arrays](./atomic-arrays.md)
127

128
### Tracing and Debugging
129

130
Comprehensive tracing system for monitoring and debugging atomic operations in concurrent code.
131

132
```kotlin { .api }
133
fun Trace(size: Int = 32, format: TraceFormat = traceFormatDefault): TraceBase
134
fun TraceBase.named(name: String): TraceBase
135

136
open class TraceFormat {
137
    open fun format(index: Int, event: Any): String
138
}
139

140
val traceFormatDefault: TraceFormat
141
```
142

143
[Tracing](./tracing.md)
144

145
### Locks and Synchronization  
146

147
Multiplatform synchronization primitives including reentrant locks and synchronized blocks.
148

149
```kotlin { .api }
150
fun reentrantLock(): ReentrantLock
151
fun <T> ReentrantLock.withLock(block: () -> T): T
152
fun <T> synchronized(lock: SynchronizedObject, block: () -> T): T
153

154
typealias SynchronizedObject = Any
155
typealias ReentrantLock = java.util.concurrent.locks.ReentrantLock
156
```
157

158
[Locks and Synchronization](./locks.md)
159

160
### Experimental Thread Parking
161

162
Low-level thread parking support for building advanced synchronization primitives.
163

164
```kotlin { .api }
165
@ExperimentalThreadBlockingApi
166
object ParkingSupport {
167
    fun park(timeout: Duration)
168
    fun parkUntil(deadline: TimeMark)
169
    fun unpark(handle: ParkingHandle)
170
    fun currentThreadHandle(): ParkingHandle
171
}
172

173
@ExperimentalThreadBlockingApi
174
typealias ParkingHandle = Thread
175
```
176

177
[Thread Parking](./thread-parking.md)
178

179
## Types
180

181
```kotlin { .api }
182
/**
183
 * Property delegate from kotlin.reflect for property-based access
184
 */
185
typealias KProperty<*> = kotlin.reflect.KProperty<*>
186

187
class AtomicRef<T> {
188
    var value: T
189
    fun lazySet(value: T)
190
    fun compareAndSet(expect: T, update: T): Boolean
191
    fun getAndSet(value: T): T
192
    operator fun getValue(thisRef: Any?, property: KProperty<*>): T
193
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: T)
194
}
195

196
// Extension functions for AtomicRef<T>
197
fun <T> AtomicRef<T>.loop(action: (T) -> Unit): Nothing
198
fun <T> AtomicRef<T>.update(function: (T) -> T)
199
fun <T> AtomicRef<T>.getAndUpdate(function: (T) -> T): T
200
fun <T> AtomicRef<T>.updateAndGet(function: (T) -> T): T
201

202
class AtomicInt {
203
    var value: Int
204
    fun lazySet(value: Int)
205
    fun compareAndSet(expect: Int, update: Int): Boolean
206
    fun getAndSet(value: Int): Int
207
    fun getAndIncrement(): Int
208
    fun getAndDecrement(): Int
209
    fun getAndAdd(delta: Int): Int
210
    fun addAndGet(delta: Int): Int
211
    fun incrementAndGet(): Int
212
    fun decrementAndGet(): Int
213
    operator fun plusAssign(delta: Int)
214
    operator fun minusAssign(delta: Int)
215
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Int
216
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Int)
217
}
218

219
// Extension functions for AtomicInt
220
fun AtomicInt.loop(action: (Int) -> Unit): Nothing
221
fun AtomicInt.update(function: (Int) -> Int)
222
fun AtomicInt.getAndUpdate(function: (Int) -> Int): Int
223
fun AtomicInt.updateAndGet(function: (Int) -> Int): Int
224

225
class AtomicLong {
226
    var value: Long
227
    fun lazySet(value: Long)
228
    fun compareAndSet(expect: Long, update: Long): Boolean
229
    fun getAndSet(value: Long): Long
230
    fun getAndIncrement(): Long
231
    fun getAndDecrement(): Long
232
    fun getAndAdd(delta: Long): Long
233
    fun addAndGet(delta: Long): Long
234
    fun incrementAndGet(): Long
235
    fun decrementAndGet(): Long
236
    operator fun plusAssign(delta: Long)
237
    operator fun minusAssign(delta: Long)
238
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Long
239
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Long)
240
}
241

242
// Extension functions for AtomicLong
243
fun AtomicLong.loop(action: (Long) -> Unit): Nothing
244
fun AtomicLong.update(function: (Long) -> Long)
245
fun AtomicLong.getAndUpdate(function: (Long) -> Long): Long
246
fun AtomicLong.updateAndGet(function: (Long) -> Long): Long
247

248
class AtomicBoolean {
249
    var value: Boolean
250
    fun lazySet(value: Boolean)
251
    fun compareAndSet(expect: Boolean, update: Boolean): Boolean
252
    fun getAndSet(value: Boolean): Boolean
253
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Boolean
254
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Boolean)
255
}
256

257
// Extension functions for AtomicBoolean
258
fun AtomicBoolean.loop(action: (Boolean) -> Unit): Nothing
259
fun AtomicBoolean.update(function: (Boolean) -> Boolean)
260
fun AtomicBoolean.getAndUpdate(function: (Boolean) -> Boolean): Boolean
261
fun AtomicBoolean.updateAndGet(function: (Boolean) -> Boolean): Boolean
262

263
open class TraceBase {
264
    open fun append(event: Any)
265
    open fun append(event1: Any, event2: Any)
266
    open fun append(event1: Any, event2: Any, event3: Any)
267
    open fun append(event1: Any, event2: Any, event3: Any, event4: Any)
268
    inline operator fun invoke(event: () -> Any)
269
    
270
    object None : TraceBase()
271
}
272
```