0
# Kotlinx Atomicfu Runtime
1

2
Kotlinx Atomicfu Runtime is a specialized runtime library for the Atomicfu compiler plugin that provides inline function implementations for atomic operations in Kotlin/JS. This library contains compiler substitution functions that simulate atomic operations in JavaScript environments where true atomic primitives are not available.
3

4
## Package Information
5

6
- **Package Name**: kotlinx-atomicfu-runtime
7
- **Package Type**: Maven (Kotlin/JS library)
8
- **Language**: Kotlin
9
- **Group ID**: org.jetbrains.kotlin
10
- **Installation**: Managed automatically by the Atomicfu compiler plugin
11

12
## Core Imports
13

14
This library is not intended for direct import by application code. The functions are automatically substituted by the Kotlin compiler during JS/IR transformation.
15

16
```kotlin
17
// This library's functions are used internally by the compiler
18
// when transforming atomicfu code from:
19
val a = atomic(0)
20
a.compareAndSet(expect, update)
21

22
// to:
23
var a = 0
24
atomicfu_compareAndSet(expect, update, { return a }, { v: Int -> a = v })
25
```
26

27
## Basic Usage
28

29
This runtime library is used transparently by the Atomicfu compiler plugin. Developers use the standard `kotlinx.atomicfu` API, and the compiler automatically transforms calls to use these runtime functions.
30

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

34
// Standard atomicfu usage - compiler transforms this automatically
35
val counter = atomic(0)
36
counter.incrementAndGet()
37
counter.compareAndSet(0, 1)
38
```
39

40
## Architecture
41

42
The runtime library follows a transformation-based approach:
43

44
- **Compiler Integration**: Functions are substituted during Kotlin/JS compilation
45
- **Getter/Setter Pattern**: All operations use lambda functions for accessing variables
46
- **No True Atomics**: Implements atomic-like behavior using regular JavaScript operations
47
- **Inline Functions**: All functions are inline for performance and proper substitution
48

49
## Capabilities
50

51
### Core Atomic Operations
52

53
Basic atomic variable operations including get, set, and compare-and-set functionality.
54

55
```kotlin { .api }
56
/**
57
 * Gets the current value of an atomic variable through getter function
58
 */
59
@PublishedApi
60
internal inline fun <T> atomicfu_getValue(
61
    `atomicfu$getter`: () -> T, 
62
    `atomicfu$setter`: (T) -> Unit
63
): T
64

65
/**
66
 * Sets the value of an atomic variable through setter function
67
 */
68
@PublishedApi
69
internal inline fun <T> atomicfu_setValue(
70
    value: T, 
71
    `atomicfu$getter`: () -> T, 
72
    `atomicfu$setter`: (T) -> Unit
73
): Unit
74

75
/**
76
 * Lazy set operation (equivalent to regular set in this JS implementation)
77
 */
78
@PublishedApi
79
internal inline fun <T> atomicfu_lazySet(
80
    value: T, 
81
    `atomicfu$getter`: () -> T, 
82
    `atomicfu$setter`: (T) -> Unit
83
): Unit
84

85
/**
86
 * Compare-and-set atomic operation, returns true if successful
87
 */
88
@PublishedApi
89
internal inline fun <T> atomicfu_compareAndSet(
90
    expect: T, 
91
    update: T, 
92
    `atomicfu$getter`: () -> T, 
93
    `atomicfu$setter`: (T) -> Unit
94
): Boolean
95

96
/**
97
 * Atomically sets value and returns the previous value
98
 */
99
@PublishedApi
100
internal inline fun <T> atomicfu_getAndSet(
101
    value: T, 
102
    `atomicfu$getter`: () -> T, 
103
    `atomicfu$setter`: (T) -> Unit
104
): T
105
```
106

107
### Integer Arithmetic Operations
108

109
Atomic arithmetic operations for Int values including increment, decrement, and addition.
110

111
```kotlin { .api }
112
/**
113
 * Increments Int value and returns the previous value
114
 */
115
@PublishedApi
116
internal inline fun atomicfu_getAndIncrement(
117
    `atomicfu$getter`: () -> Int, 
118
    `atomicfu$setter`: (Int) -> Unit
119
): Int
120

121
/**
122
 * Increments Int value and returns the new value
123
 */
124
@PublishedApi
125
internal inline fun atomicfu_incrementAndGet(
126
    `atomicfu$getter`: () -> Int, 
127
    `atomicfu$setter`: (Int) -> Unit
128
): Int
129

130
/**
131
 * Decrements Int value and returns the previous value
132
 */
133
@PublishedApi
134
internal inline fun atomicfu_getAndDecrement(
135
    `atomicfu$getter`: () -> Int, 
136
    `atomicfu$setter`: (Int) -> Unit
137
): Int
138

139
/**
140
 * Decrements Int value and returns the new value
141
 */
142
@PublishedApi
143
internal inline fun atomicfu_decrementAndGet(
144
    `atomicfu$getter`: () -> Int, 
145
    `atomicfu$setter`: (Int) -> Unit
146
): Int
147

148
/**
149
 * Adds Int value and returns the previous value
150
 */
151
@PublishedApi
152
internal inline fun atomicfu_getAndAdd(
153
    value: Int, 
154
    `atomicfu$getter`: () -> Int, 
155
    `atomicfu$setter`: (Int) -> Unit
156
): Int
157

158
/**
159
 * Adds Int value and returns the new value
160
 */
161
@PublishedApi
162
internal inline fun atomicfu_addAndGet(
163
    value: Int, 
164
    `atomicfu$getter`: () -> Int, 
165
    `atomicfu$setter`: (Int) -> Unit
166
): Int
167
```
168

169
### Long Arithmetic Operations
170

171
Atomic arithmetic operations for Long values including increment, decrement, and addition.
172

173
```kotlin { .api }
174
/**
175
 * Increments Long value and returns the previous value
176
 */
177
@PublishedApi
178
internal inline fun atomicfu_getAndIncrement(
179
    `atomicfu$getter`: () -> Long, 
180
    `atomicfu$setter`: (Long) -> Unit
181
): Long
182

183
/**
184
 * Increments Long value and returns the new value
185
 */
186
@PublishedApi
187
internal inline fun atomicfu_incrementAndGet(
188
    `atomicfu$getter`: () -> Long, 
189
    `atomicfu$setter`: (Long) -> Unit
190
): Long
191

192
/**
193
 * Decrements Long value and returns the previous value
194
 */
195
@PublishedApi
196
internal inline fun atomicfu_getAndDecrement(
197
    `atomicfu$getter`: () -> Long, 
198
    `atomicfu$setter`: (Long) -> Unit
199
): Long
200

201
/**
202
 * Decrements Long value and returns the new value
203
 */
204
@PublishedApi
205
internal inline fun atomicfu_decrementAndGet(
206
    `atomicfu$getter`: () -> Long, 
207
    `atomicfu$setter`: (Long) -> Unit
208
): Long
209

210
/**
211
 * Adds Long value and returns the previous value
212
 */
213
@PublishedApi
214
internal inline fun atomicfu_getAndAdd(
215
    value: Long, 
216
    `atomicfu$getter`: () -> Long, 
217
    `atomicfu$setter`: (Long) -> Unit
218
): Long
219

220
/**
221
 * Adds Long value and returns the new value
222
 */
223
@PublishedApi
224
internal inline fun atomicfu_addAndGet(
225
    value: Long, 
226
    `atomicfu$getter`: () -> Long, 
227
    `atomicfu$setter`: (Long) -> Unit
228
): Long
229
```
230

231
### Functional Update Operations
232

233
Advanced atomic operations that apply functions to values with retry logic for consistency.
234

235
```kotlin { .api }
236
/**
237
 * Infinite loop that continuously applies action to current value
238
 * @param action Function to apply to each current value
239
 * @return Never returns (Nothing type)
240
 */
241
@PublishedApi
242
internal inline fun <T> atomicfu_loop(
243
    action: (T) -> Unit, 
244
    `atomicfu$getter`: () -> T, 
245
    `atomicfu$setter`: (T) -> Unit
246
): Nothing
247

248
/**
249
 * Atomically updates value using provided function (retries on failure)
250
 * @param function Transformation function to apply to current value
251
 */
252
@PublishedApi
253
internal inline fun <T> atomicfu_update(
254
    function: (T) -> T, 
255
    `atomicfu$getter`: () -> T, 
256
    `atomicfu$setter`: (T) -> Unit
257
)
258

259
/**
260
 * Atomically updates value and returns the previous value
261
 * @param function Transformation function to apply to current value
262
 * @return The value before transformation
263
 */
264
@PublishedApi
265
internal inline fun <T> atomicfu_getAndUpdate(
266
    function: (T) -> T, 
267
    `atomicfu$getter`: () -> T, 
268
    `atomicfu$setter`: (T) -> Unit
269
): T
270

271
/**
272
 * Atomically updates value and returns the new value
273
 * @param function Transformation function to apply to current value
274
 * @return The value after transformation
275
 */
276
@PublishedApi
277
internal inline fun <T> atomicfu_updateAndGet(
278
    function: (T) -> T, 
279
    `atomicfu$getter`: () -> T, 
280
    `atomicfu$setter`: (T) -> Unit
281
): T
282
```
283

284
## Implementation Details
285

286
### Transformation Pattern
287

288
The compiler transforms atomicfu API calls into calls to these runtime functions:
289

290
```kotlin
291
// Original atomicfu code:
292
val a = atomic(0)
293
a.compareAndSet(expect, update)
294

295
// Transformed to:
296
var a = 0
297
atomicfu_compareAndSet(expect, update, { return a }, { v: Int -> a = v })
298
```
299

300
### Getter/Setter Functions
301

302
All operations take lambda functions for variable access:
303
- `atomicfu$getter: () -> T` - Function that returns the current value
304
- `atomicfu$setter: (T) -> Unit` - Function that sets a new value
305

306
### Retry Logic
307

308
Functional update operations use retry loops with compare-and-set to ensure consistency:
309

310
```kotlin
311
// Example of retry pattern used in atomicfu_update
312
while (true) {
313
    val cur = atomicfu$getter()
314
    val upd = function(cur)
315
    if (atomicfu_compareAndSet(cur, upd, atomicfu$getter, atomicfu$setter)) return
316
}
317
```
318

319
### JavaScript Compatibility
320

321
Since JavaScript doesn't have true atomic operations, this library provides:
322
- Simple equality checks for compare-and-set operations
323
- Regular variable access through getter/setter functions
324
- Synchronous operation execution (no actual threading concerns in JS)
325

326
## Annotations
327

328
All functions use these Kotlin annotations:
329

330
- `@PublishedApi` - Makes internal functions available for inlining across modules
331
- `internal` - Restricts direct access from user code
332
- `inline` - Enables inlining for performance and proper compiler substitution