0
# Atomicfu
1

2
Atomicfu is a multiplatform Kotlin compiler plugin and library that provides atomic operations across JVM, Native, JS, and Wasm platforms. It enables developers to write idiomatic atomic operations like boxed values while running them efficiently in production with platform-specific optimizations.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlin:kotlin-atomicfu-compiler-plugin
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  - Library dependency: `implementation("org.jetbrains.kotlinx:atomicfu:0.25.0")`
11
  - Compiler plugin: `id("kotlinx-atomicfu")` in build.gradle.kts
12

13
## Core Imports
14

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

19
## Basic Usage
20

21
```kotlin
22
import kotlinx.atomicfu.*
23

24
class Counter {
25
    private val count = atomic(0)
26
    
27
    fun increment(): Int = count.incrementAndGet()
28
    
29
    fun get(): Int = count.value
30
    
31
    fun compareAndSet(expected: Int, newValue: Int): Boolean = 
32
        count.compareAndSet(expected, newValue)
33
}
34

35
// Usage example
36
val counter = Counter()
37
counter.increment() // Returns 1
38
counter.compareAndSet(1, 10) // Returns true, sets value to 10
39
```
40

41
## Architecture
42

43
Atomicfu is built around several key components:
44

45
- **Compiler Plugin**: Transforms high-level atomic operations into platform-specific implementations
46
- **Factory Functions**: `atomic()` functions create appropriate atomic wrappers for different types
47
- **Atomic Types**: Type-safe wrappers (`AtomicInt`, `AtomicLong`, `AtomicBoolean`, `AtomicRef`) with comprehensive operation sets
48
- **Array Types**: Atomic arrays for bulk operations (`AtomicIntArray`, `AtomicLongArray`, etc.)
49
- **Platform Optimization**: JVM uses `java.util.concurrent.atomic.*`, Native uses intrinsics, JS/Wasm use runtime implementations
50
- **Gradle Plugin**: Configuration for enabling transformations across different platforms
51

52
## Capabilities
53

54
### Atomic Operations
55

56
Core atomic operations for thread-safe programming with compare-and-swap, arithmetic operations, high-level update patterns, tracing, and delegated properties.
57

58
```kotlin { .api }
59
fun atomic(value: Int): AtomicInt
60
fun atomic(value: Long): AtomicLong
61
fun atomic(value: Boolean): AtomicBoolean
62
fun <T> atomic(value: T): AtomicRef<T>
63

64
// With tracing support
65
fun atomic(value: Int, trace: Trace): AtomicInt
66
fun <T> atomic(value: T, trace: Trace): AtomicRef<T>
67

68
// Delegated property support
69
var property: T by atomic(initialValue)
70
```
71

72
[Atomic Operations](./atomic-operations.md)
73

74
### Atomic Arrays
75

76
Arrays of atomic values for bulk operations and indexed atomic access patterns.
77

78
```kotlin { .api }
79
class AtomicIntArray(size: Int)
80
class AtomicLongArray(size: Int)
81
class AtomicBooleanArray(size: Int)
82
fun <T> atomicArrayOfNulls(size: Int): AtomicArray<T?>
83
```
84

85
[Atomic Arrays](./atomic-arrays.md)
86

87
### Gradle Plugin Configuration
88

89
Configuration options for enabling atomicfu transformations across different Kotlin platforms.
90

91
```kotlin { .api }
92
class AtomicfuKotlinGradleExtension {
93
    var isJsIrTransformationEnabled: Boolean
94
    var isJvmIrTransformationEnabled: Boolean
95
    var isNativeIrTransformationEnabled: Boolean
96
}
97
```
98

99
[Plugin Configuration](./plugin-configuration.md)
100

101
### Lock-Free Synchronization
102

103
Reentrant locks and lock-free synchronization primitives for thread-safe coordination without blocking.
104

105
```kotlin { .api }
106
fun reentrantLock(): ReentrantLock
107

108
class ReentrantLock {
109
    fun lock(): Unit
110
    fun unlock(): Unit
111
    fun tryLock(): Boolean
112
    inline fun <T> withLock(action: () -> T): T
113
}
114
```
115

116
[Lock-Free Synchronization](./lock-free-synchronization.md)