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.

—

Pending

Overview

Eval results

Files

Atomic Operations

Name: tessl/maven-org-jetbrains-kotlinx--atomicfu-jvm
Author: tessl

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

Capabilities

Atomic Reference Factory Functions

Creates atomic reference variables for any type with optional tracing support.

/**
 * Creates atomic reference with a given initial value.
 * Can only be used to initialize private read-only properties.
 */
fun <T> atomic(initial: T): AtomicRef<T>

/**
 * Creates atomic reference with tracing support for debugging.
 */
fun <T> atomic(initial: T, trace: TraceBase): AtomicRef<T>

Usage Examples:

import kotlinx.atomicfu.*

class DataStore {
    private val currentData = atomic<String?>(null)
    private val config = atomic(emptyMap<String, Any>())
    
    fun setData(data: String?) {
        currentData.value = data
    }
    
    fun getData(): String? = currentData.value
    
    fun updateConfig(key: String, value: Any) {
        val currentConfig = config.value
        config.value = currentConfig + (key to value)
    }
}

Atomic Integer Factory Functions

Creates atomic integer variables with arithmetic operations support.

/**
 * Creates atomic Int with a given initial value.
 * Can only be used to initialize private read-only properties.
 */
fun atomic(initial: Int): AtomicInt

/**
 * Creates atomic Int with tracing support for debugging.
 */
fun atomic(initial: Int, trace: TraceBase): AtomicInt

Usage Examples:

import kotlinx.atomicfu.*

class Counter {
    private val count = atomic(0)
    private val maxSeen = atomic(Int.MIN_VALUE)
    
    fun increment(): Int {
        val newValue = count.incrementAndGet()
        // Update max atomically
        while (true) {
            val currentMax = maxSeen.value
            if (newValue <= currentMax || maxSeen.compareAndSet(currentMax, newValue)) {
                break
            }
        }
        return newValue
    }
    
    fun add(delta: Int): Int = count.addAndGet(delta)
    
    fun get(): Int = count.value
    
    fun getMax(): Int = maxSeen.value
}

Atomic Long Factory Functions

Creates atomic long variables with arithmetic operations support.

/**
 * Creates atomic Long with a given initial value.
 * Can only be used to initialize private read-only properties.
 */
fun atomic(initial: Long): AtomicLong

/**
 * Creates atomic Long with tracing support for debugging.
 */
fun atomic(initial: Long, trace: TraceBase): AtomicLong

Usage Examples:

import kotlinx.atomicfu.*

class Accumulator {
    private val total = atomic(0L)
    private val operations = atomic(0L)
    
    fun add(value: Long) {
        total += value
        operations.incrementAndGet()
    }
    
    fun getAverage(): Double {
        val currentTotal = total.value
        val currentOps = operations.value
        return if (currentOps > 0) currentTotal.toDouble() / currentOps else 0.0
    }
}

Atomic Boolean Factory Functions

Creates atomic boolean variables for flag and state management.

/**
 * Creates atomic Boolean with a given initial value.
 * Can only be used to initialize private read-only properties.
 */
fun atomic(initial: Boolean): AtomicBoolean

/**
 * Creates atomic Boolean with tracing support for debugging.
 */
fun atomic(initial: Boolean, trace: TraceBase): AtomicBoolean

Usage Examples:

import kotlinx.atomicfu.*

class ServiceState {
    private val isRunning = atomic(false)
    private val isInitialized = atomic(false)
    
    fun start(): Boolean {
        if (!isInitialized.value) {
            throw IllegalStateException("Service not initialized")
        }
        return isRunning.compareAndSet(false, true)
    }
    
    fun stop(): Boolean {
        return isRunning.compareAndSet(true, false)
    }
    
    fun initialize(): Boolean {
        return isInitialized.compareAndSet(false, true)
    }
    
    fun isRunning(): Boolean = isRunning.value
}

AtomicRef Operations

Generic atomic reference with volatile reads/writes and atomic operations.

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

class AtomicRef<T> {
    /** Volatile property for reading/writing the atomic value */
    var value: T
    
    /** Property delegate getter */
    operator fun getValue(thisRef: Any?, property: KProperty<*>): T
    
    /** Property delegate setter */
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: T)
    
    /** Maps to AtomicReferenceFieldUpdater.lazySet */
    fun lazySet(value: T)
    
    /** Maps to AtomicReferenceFieldUpdater.compareAndSet */ 
    fun compareAndSet(expect: T, update: T): Boolean
    
    /** Maps to AtomicReferenceFieldUpdater.getAndSet */
    fun getAndSet(value: T): T
}

AtomicInt Operations

Atomic integer with volatile reads/writes and atomic arithmetic operations.

class AtomicInt {
    /** Volatile property for reading/writing the atomic value */
    var value: Int
    
    /** Property delegate operations */
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Int
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Int)
    
    /** Basic atomic operations */
    fun lazySet(value: Int)
    fun compareAndSet(expect: Int, update: Int): Boolean
    fun getAndSet(value: Int): Int
    
    /** Atomic arithmetic operations */
    fun getAndIncrement(): Int
    fun getAndDecrement(): Int
    fun getAndAdd(delta: Int): Int
    fun addAndGet(delta: Int): Int
    fun incrementAndGet(): Int
    fun decrementAndGet(): Int
    
    /** Operator overloads for atomic arithmetic */
    operator fun plusAssign(delta: Int)
    operator fun minusAssign(delta: Int)
}

AtomicLong Operations

Atomic long with volatile reads/writes and atomic arithmetic operations.

class AtomicLong {
    /** Volatile property for reading/writing the atomic value */
    var value: Long
    
    /** Property delegate operations */
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Long
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Long)
    
    /** Basic atomic operations */
    fun lazySet(value: Long)
    fun compareAndSet(expect: Long, update: Long): Boolean
    fun getAndSet(value: Long): Long
    
    /** Atomic arithmetic operations */
    fun getAndIncrement(): Long
    fun getAndDecrement(): Long
    fun getAndAdd(delta: Long): Long
    fun addAndGet(delta: Long): Long
    fun incrementAndGet(): Long
    fun decrementAndGet(): Long
    
    /** Operator overloads for atomic arithmetic */
    operator fun plusAssign(delta: Long)
    operator fun minusAssign(delta: Long)
}

AtomicBoolean Operations

Atomic boolean with volatile reads/writes and atomic operations.

class AtomicBoolean {
    /** Volatile property for reading/writing the atomic value */
    var value: Boolean
    
    /** Property delegate operations */
    operator fun getValue(thisRef: Any?, property: KProperty<*>): Boolean
    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: Boolean)
    
    /** Basic atomic operations */
    fun lazySet(value: Boolean)
    fun compareAndSet(expect: Boolean, update: Boolean): Boolean
    fun getAndSet(value: Boolean): Boolean
}

Extension Functions

Higher-level atomic operations built on top of basic compare-and-swap operations.

/** Infinite loop that reads atomic variable and performs action on its value */
fun <T> AtomicRef<T>.loop(action: (T) -> Unit): Nothing
fun AtomicInt.loop(action: (Int) -> Unit): Nothing
fun AtomicLong.loop(action: (Long) -> Unit): Nothing
fun AtomicBoolean.loop(action: (Boolean) -> Unit): Nothing

/** Updates variable atomically using the specified function */
fun <T> AtomicRef<T>.update(function: (T) -> T)
fun AtomicInt.update(function: (Int) -> Int)
fun AtomicLong.update(function: (Long) -> Long)
fun AtomicBoolean.update(function: (Boolean) -> Boolean)

/** Updates variable atomically and returns old value */
fun <T> AtomicRef<T>.getAndUpdate(function: (T) -> T): T
fun AtomicInt.getAndUpdate(function: (Int) -> Int): Int
fun AtomicLong.getAndUpdate(function: (Long) -> Long): Long
fun AtomicBoolean.getAndUpdate(function: (Boolean) -> Boolean): Boolean

/** Updates variable atomically and returns new value */
fun <T> AtomicRef<T>.updateAndGet(function: (T) -> T): T
fun AtomicInt.updateAndGet(function: (Int) -> Int): Int
fun AtomicLong.updateAndGet(function: (Long) -> Long): Long
fun AtomicBoolean.updateAndGet(function: (Boolean) -> Boolean): Boolean

Usage Examples:

import kotlinx.atomicfu.*

class Statistics {
    private val values = atomic<List<Double>>(emptyList())
    private val sum = atomic(0.0)
    
    fun addValue(value: Double) {
        // Update list atomically
        values.update { currentList -> currentList + value }
        
        // Update sum atomically
        sum.update { currentSum -> currentSum + value }
    }
    
    fun getAverage(): Double {
        val currentValues = values.value
        return if (currentValues.isNotEmpty()) sum.value / currentValues.size else 0.0
    }
    
    fun clear() {
        values.update { emptyList() }
        sum.update { 0.0 }
    }
}

Implementation Notes

Usage Constraints

Atomic fields must be declared as private or internal val properties
Format: private val field = atomic(initialValue)
Cannot be used with var properties or public fields
Atomic operations are transformed at compile-time for optimal performance

JVM Optimizations

Uses AtomicXxxFieldUpdater for optimal performance
VarHandle support for Java 9+ when available
Zero runtime overhead through bytecode transformation
Direct mapping to JVM atomic operations

Install with Tessl CLI

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

docs

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