kotlinx-atomicfu

To ensure the compiler plugin can correctly transform your code into efficient atomic operations, follow these constraints:

1. Encapsulation: Declare atomic variables as private val or internal val. Do not allow direct access to the atomic variable itself outside of your Kotlin module. To expose the value, use a delegated property:

   private val _foo = atomic<T>(initial)
   public var foo: T by _foo

2. No Leaking References: Do not read references of atomic variables into local variables (e.g., val tmp = top is forbidden) or leak them via return values or parameters.
3. Simple Operations Only: Avoid complex data flow in parameters. Expressions like top.value = complex_expression or top.compareAndSet(cur, complex_expression) are not supported if the expression contains branches. Extract the expression into a local variable first.
4. Direct Access: Only simple operations performed directly on the atomic variable are supported.

Maven configuration is supported for JVM projects. You must declare the version, provide the dependency with provided scope, and configure build steps to transform the classes.

1. Declare version and dependency

<properties>
     <atomicfu.version>0.33.0</atomicfu.version>
</properties> 

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>atomicfu</artifactId>
        <version>${atomicfu.version}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

2. Configure Build Steps

Configure the kotlin-maven-plugin to output to a staging directory (classes-pre-atomicfu), then use the atomicfu-maven-plugin to transform those classes.

<build>
  <plugins>
    <plugin>
      <groupId>org.jetbrains.kotlin</groupId>
      <artifactId>kotlin-maven-plugin</artifactId>
      <version>${kotlin.version}</version>
      <executions>
        <execution>
          <id>compile</id>
          <phase>compile</phase>
          <goals>
            <goal>compile</goal>
          </goals>
          <configuration>
            <output>${project.build.directory}/classes-pre-atomicfu</output>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <plugin>
      <groupId>org.jetbrains.kotlinx</groupId>
      <artifactId>atomicfu-maven-plugin</artifactId>
      <version>${atomicfu.version}</version>
      <executions>
        <execution>
          <goals>
            <goal>transform</goal>
          </goals>
          <configuration>
            <input>${project.build.directory}/classes-pre-atomicfu</input>
            <!-- "VH" to use Java 9 VarHandle, "BOTH" to produce multi-version code -->
            <variant>FU</variant>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

You can configure how AtomicFU transforms atomics on the JVM and JS by adding an atomicfu block to your build.gradle file. This is useful for controlling which Java classes replace atomics during bytecode transformation.

Available Configuration Options:

• dependenciesVersion: The version of AtomicFU dependencies to use (set to null to turn off auto dependencies).
• transformJvm: Boolean flag to enable or disable JVM transformation (defaults to true).
• jvmVariant: Defines the replacement strategy for JVM atomics:
  • FU: Uses AtomicXxxFieldUpdater.
  • VH: Uses VarHandle (requires JDK 9+).
  • BOTH: Creates a multi-release JAR containing both FU (for JDK <= 8) and VH (for JDK 9+).

Note for JS users: The transformJs flag is disabled by default and has no effect since version 0.26.0. You should remove it from your configuration.

atomicfu {
  dependenciesVersion = '0.33.0'
  transformJvm = true
  jvmVariant = "FU"
}

AtomicFU allows you to declare atomic variables and perform lock-free operations using idiomatic Kotlin syntax.

Declaration

Use atomic(initialValue) to declare an atomic variable. For integers and longs, type inference works automatically:

import kotlinx.atomicfu.*

private val top = atomic<Node?>(null) // Atomic reference
val myInt = atomic(0)               // Atomic integer
val myLong = atomic(0L)              // Atomic long

Volatile Reads and Writes

Use the .value property for volatile access:

fun isEmpty() = top.value == null  // volatile read
fun clear() { top.value = null }   // volatile write

Atomic Updates

For lock-free logic, use compareAndSet or higher-level extension functions like update, updateAndGet, and getAndUpdate:

// Direct CAS
if (top.compareAndSet(expect, update)) { ... }

// Idiomatic updates
fun push(v: Value) = top.update { cur -> Node(v, cur) }
fun pop(): Value? = top.getAndUpdate { cur -> cur?.next }?.value

// Looping primitive
top.loop { cur -> 
   // while(true) loop that volatile-reads current value
}

Integer/Long Operations

Atomic integers and longs support standard operations like getAndIncrement(), incrementAndGet(), getAndAdd(), etc., as well as += and -= operators.