or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-jetbrains-kotlin--kotlinx-atomicfu-runtime

Runtime library for the Atomicfu compiler plugin that provides inline function implementations for atomic operations in Kotlin/JS.

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

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlin--kotlinx-atomicfu-runtime@2.3.0

index.mddocs/

Kotlinx Atomicfu Runtime

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.

Package Information

  • Package Name: kotlinx-atomicfu-runtime
  • Package Type: Maven (Kotlin/JS library)
  • Language: Kotlin
  • Group ID: org.jetbrains.kotlin
  • Installation: Managed automatically by the Atomicfu compiler plugin

Core Imports

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

// This library's functions are used internally by the compiler
// when transforming atomicfu code from:
val a = atomic(0)
a.compareAndSet(expect, update)

// to:
var a = 0
atomicfu_compareAndSet(expect, update, { return a }, { v: Int -> a = v })

Basic Usage

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.

import kotlinx.atomicfu.*

// Standard atomicfu usage - compiler transforms this automatically
val counter = atomic(0)
counter.incrementAndGet()
counter.compareAndSet(0, 1)

Architecture

The runtime library follows a transformation-based approach:

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

Capabilities

Core Atomic Operations

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

/**
 * Gets the current value of an atomic variable through getter function
 */
@PublishedApi
internal inline fun <T> atomicfu_getValue(
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): T

/**
 * Sets the value of an atomic variable through setter function
 */
@PublishedApi
internal inline fun <T> atomicfu_setValue(
    value: T, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): Unit

/**
 * Lazy set operation (equivalent to regular set in this JS implementation)
 */
@PublishedApi
internal inline fun <T> atomicfu_lazySet(
    value: T, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): Unit

/**
 * Compare-and-set atomic operation, returns true if successful
 */
@PublishedApi
internal inline fun <T> atomicfu_compareAndSet(
    expect: T, 
    update: T, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): Boolean

/**
 * Atomically sets value and returns the previous value
 */
@PublishedApi
internal inline fun <T> atomicfu_getAndSet(
    value: T, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): T

Integer Arithmetic Operations

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

/**
 * Increments Int value and returns the previous value
 */
@PublishedApi
internal inline fun atomicfu_getAndIncrement(
    `atomicfu$getter`: () -> Int, 
    `atomicfu$setter`: (Int) -> Unit
): Int

/**
 * Increments Int value and returns the new value
 */
@PublishedApi
internal inline fun atomicfu_incrementAndGet(
    `atomicfu$getter`: () -> Int, 
    `atomicfu$setter`: (Int) -> Unit
): Int

/**
 * Decrements Int value and returns the previous value
 */
@PublishedApi
internal inline fun atomicfu_getAndDecrement(
    `atomicfu$getter`: () -> Int, 
    `atomicfu$setter`: (Int) -> Unit
): Int

/**
 * Decrements Int value and returns the new value
 */
@PublishedApi
internal inline fun atomicfu_decrementAndGet(
    `atomicfu$getter`: () -> Int, 
    `atomicfu$setter`: (Int) -> Unit
): Int

/**
 * Adds Int value and returns the previous value
 */
@PublishedApi
internal inline fun atomicfu_getAndAdd(
    value: Int, 
    `atomicfu$getter`: () -> Int, 
    `atomicfu$setter`: (Int) -> Unit
): Int

/**
 * Adds Int value and returns the new value
 */
@PublishedApi
internal inline fun atomicfu_addAndGet(
    value: Int, 
    `atomicfu$getter`: () -> Int, 
    `atomicfu$setter`: (Int) -> Unit
): Int

Long Arithmetic Operations

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

/**
 * Increments Long value and returns the previous value
 */
@PublishedApi
internal inline fun atomicfu_getAndIncrement(
    `atomicfu$getter`: () -> Long, 
    `atomicfu$setter`: (Long) -> Unit
): Long

/**
 * Increments Long value and returns the new value
 */
@PublishedApi
internal inline fun atomicfu_incrementAndGet(
    `atomicfu$getter`: () -> Long, 
    `atomicfu$setter`: (Long) -> Unit
): Long

/**
 * Decrements Long value and returns the previous value
 */
@PublishedApi
internal inline fun atomicfu_getAndDecrement(
    `atomicfu$getter`: () -> Long, 
    `atomicfu$setter`: (Long) -> Unit
): Long

/**
 * Decrements Long value and returns the new value
 */
@PublishedApi
internal inline fun atomicfu_decrementAndGet(
    `atomicfu$getter`: () -> Long, 
    `atomicfu$setter`: (Long) -> Unit
): Long

/**
 * Adds Long value and returns the previous value
 */
@PublishedApi
internal inline fun atomicfu_getAndAdd(
    value: Long, 
    `atomicfu$getter`: () -> Long, 
    `atomicfu$setter`: (Long) -> Unit
): Long

/**
 * Adds Long value and returns the new value
 */
@PublishedApi
internal inline fun atomicfu_addAndGet(
    value: Long, 
    `atomicfu$getter`: () -> Long, 
    `atomicfu$setter`: (Long) -> Unit
): Long

Functional Update Operations

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

/**
 * Infinite loop that continuously applies action to current value
 * @param action Function to apply to each current value
 * @return Never returns (Nothing type)
 */
@PublishedApi
internal inline fun <T> atomicfu_loop(
    action: (T) -> Unit, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): Nothing

/**
 * Atomically updates value using provided function (retries on failure)
 * @param function Transformation function to apply to current value
 */
@PublishedApi
internal inline fun <T> atomicfu_update(
    function: (T) -> T, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
)

/**
 * Atomically updates value and returns the previous value
 * @param function Transformation function to apply to current value
 * @return The value before transformation
 */
@PublishedApi
internal inline fun <T> atomicfu_getAndUpdate(
    function: (T) -> T, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): T

/**
 * Atomically updates value and returns the new value
 * @param function Transformation function to apply to current value
 * @return The value after transformation
 */
@PublishedApi
internal inline fun <T> atomicfu_updateAndGet(
    function: (T) -> T, 
    `atomicfu$getter`: () -> T, 
    `atomicfu$setter`: (T) -> Unit
): T

Implementation Details

Transformation Pattern

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

// Original atomicfu code:
val a = atomic(0)
a.compareAndSet(expect, update)

// Transformed to:
var a = 0
atomicfu_compareAndSet(expect, update, { return a }, { v: Int -> a = v })

Getter/Setter Functions

All operations take lambda functions for variable access:

  • atomicfu$getter: () -> T - Function that returns the current value
  • atomicfu$setter: (T) -> Unit - Function that sets a new value

Retry Logic

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

// Example of retry pattern used in atomicfu_update
while (true) {
    val cur = atomicfu$getter()
    val upd = function(cur)
    if (atomicfu_compareAndSet(cur, upd, atomicfu$getter, atomicfu$setter)) return
}

JavaScript Compatibility

Since JavaScript doesn't have true atomic operations, this library provides:

  • Simple equality checks for compare-and-set operations
  • Regular variable access through getter/setter functions
  • Synchronous operation execution (no actual threading concerns in JS)

Annotations

All functions use these Kotlin annotations:

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