or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

atomic-arrays.mdatomic-operations.mdindex.mdlocks.mdthread-parking.mdtracing.md
tile.json

tessl/maven-org-jetbrains-kotlinx--atomicfu-jvm

AtomicFU JVM-specific artifact providing idiomatic and efficient atomic operations optimized for the JVM platform using AtomicXxxFieldUpdater or VarHandle.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlinx/atomicfu-jvm@0.29.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlinx--atomicfu-jvm@0.29.0

index.mddocs/

AtomicFU JVM

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.

Package Information

  • Package Name: org.jetbrains.kotlinx:atomicfu-jvm
  • Package Type: maven (Gradle/Maven)
  • Language: Kotlin
  • Installation:
    • Gradle: implementation("org.jetbrains.kotlinx:atomicfu-jvm:0.29.0")
    • Maven: <dependency><groupId>org.jetbrains.kotlinx</groupId><artifactId>atomicfu-jvm</artifactId><version>0.29.0</version></dependency>

Core Imports

import kotlinx.atomicfu.*

For specific functionality:

import kotlinx.atomicfu.atomic
import kotlinx.atomicfu.AtomicRef
import kotlinx.atomicfu.AtomicInt
import kotlinx.atomicfu.AtomicLong
import kotlinx.atomicfu.AtomicBoolean

For locks and synchronization:

import kotlinx.atomicfu.locks.*

For tracing:

import kotlinx.atomicfu.Trace
import kotlinx.atomicfu.TraceBase

Basic Usage

import kotlinx.atomicfu.*

class Counter {
    // Atomic fields must be private read-only properties
    private val count = atomic(0)
    private val name = atomic<String?>(null)
    
    fun increment(): Int = count.incrementAndGet()
    
    fun getName(): String? = name.value
    
    fun setName(newName: String) {
        name.value = newName
    }
    
    fun compareAndSwapName(expected: String?, newName: String): Boolean =
        name.compareAndSet(expected, newName)
}

// Usage
val counter = Counter()
println(counter.increment()) // 1
println(counter.increment()) // 2

counter.setName("MyCounter")
println(counter.getName()) // "MyCounter"

Architecture

AtomicFU is built around several key components:

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

Capabilities

Atomic Operations

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

fun <T> atomic(initial: T): AtomicRef<T>
fun <T> atomic(initial: T, trace: TraceBase): AtomicRef<T>
fun atomic(initial: Int): AtomicInt
fun atomic(initial: Int, trace: TraceBase): AtomicInt
fun atomic(initial: Long): AtomicLong
fun atomic(initial: Long, trace: TraceBase): AtomicLong
fun atomic(initial: Boolean): AtomicBoolean
fun atomic(initial: Boolean, trace: TraceBase): AtomicBoolean

Atomic Operations

Atomic Arrays

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

fun <T> atomicArrayOfNulls(size: Int): AtomicArray<T?>

class AtomicIntArray(size: Int) {
    val size: Int
    operator fun get(index: Int): AtomicInt
}

class AtomicLongArray(size: Int) {
    val size: Int
    operator fun get(index: Int): AtomicLong
}

class AtomicBooleanArray(size: Int) {
    val size: Int
    operator fun get(index: Int): AtomicBoolean
}

Atomic Arrays

Tracing and Debugging

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

fun Trace(size: Int = 32, format: TraceFormat = traceFormatDefault): TraceBase
fun TraceBase.named(name: String): TraceBase

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

val traceFormatDefault: TraceFormat

Tracing

Locks and Synchronization

Multiplatform synchronization primitives including reentrant locks and synchronized blocks.

fun reentrantLock(): ReentrantLock
fun <T> ReentrantLock.withLock(block: () -> T): T
fun <T> synchronized(lock: SynchronizedObject, block: () -> T): T

typealias SynchronizedObject = Any
typealias ReentrantLock = java.util.concurrent.locks.ReentrantLock

Locks and Synchronization

Experimental Thread Parking

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

@ExperimentalThreadBlockingApi
object ParkingSupport {
    fun park(timeout: Duration)
    fun parkUntil(deadline: TimeMark)
    fun unpark(handle: ParkingHandle)
    fun currentThreadHandle(): ParkingHandle
}

@ExperimentalThreadBlockingApi
typealias ParkingHandle = Thread

Thread Parking

Types

/**
 * Property delegate from kotlin.reflect for property-based access
 */
typealias KProperty<*> = kotlin.reflect.KProperty<*>

class AtomicRef<T> {
    var value: T
    fun lazySet(value: T)
    fun compareAndSet(expect: T, update: T): Boolean
    fun getAndSet(value: T): T
    operator fun getValue(thisRef: Any?, property: KProperty<*>): T
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: T)
}

// Extension functions for AtomicRef<T>
fun <T> AtomicRef<T>.loop(action: (T) -> Unit): Nothing
fun <T> AtomicRef<T>.update(function: (T) -> T)
fun <T> AtomicRef<T>.getAndUpdate(function: (T) -> T): T
fun <T> AtomicRef<T>.updateAndGet(function: (T) -> T): T

class AtomicInt {
    var value: Int
    fun lazySet(value: Int)
    fun compareAndSet(expect: Int, update: Int): Boolean
    fun getAndSet(value: Int): Int
    fun getAndIncrement(): Int
    fun getAndDecrement(): Int
    fun getAndAdd(delta: Int): Int
    fun addAndGet(delta: Int): Int
    fun incrementAndGet(): Int
    fun decrementAndGet(): Int
    operator fun plusAssign(delta: Int)
    operator fun minusAssign(delta: Int)
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Int
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Int)
}

// Extension functions for AtomicInt
fun AtomicInt.loop(action: (Int) -> Unit): Nothing
fun AtomicInt.update(function: (Int) -> Int)
fun AtomicInt.getAndUpdate(function: (Int) -> Int): Int
fun AtomicInt.updateAndGet(function: (Int) -> Int): Int

class AtomicLong {
    var value: Long
    fun lazySet(value: Long)
    fun compareAndSet(expect: Long, update: Long): Boolean
    fun getAndSet(value: Long): Long
    fun getAndIncrement(): Long
    fun getAndDecrement(): Long
    fun getAndAdd(delta: Long): Long
    fun addAndGet(delta: Long): Long
    fun incrementAndGet(): Long
    fun decrementAndGet(): Long
    operator fun plusAssign(delta: Long)
    operator fun minusAssign(delta: Long)
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Long
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Long)
}

// Extension functions for AtomicLong
fun AtomicLong.loop(action: (Long) -> Unit): Nothing
fun AtomicLong.update(function: (Long) -> Long)
fun AtomicLong.getAndUpdate(function: (Long) -> Long): Long
fun AtomicLong.updateAndGet(function: (Long) -> Long): Long

class AtomicBoolean {
    var value: Boolean
    fun lazySet(value: Boolean)
    fun compareAndSet(expect: Boolean, update: Boolean): Boolean
    fun getAndSet(value: Boolean): Boolean
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Boolean
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Boolean)
}

// Extension functions for AtomicBoolean
fun AtomicBoolean.loop(action: (Boolean) -> Unit): Nothing
fun AtomicBoolean.update(function: (Boolean) -> Boolean)
fun AtomicBoolean.getAndUpdate(function: (Boolean) -> Boolean): Boolean
fun AtomicBoolean.updateAndGet(function: (Boolean) -> Boolean): Boolean

open class TraceBase {
    open fun append(event: Any)
    open fun append(event1: Any, event2: Any)
    open fun append(event1: Any, event2: Any, event3: Any)
    open fun append(event1: Any, event2: Any, event3: Any, event4: Any)
    inline operator fun invoke(event: () -> Any)
    
    object None : TraceBase()
}