Home

Awesome

AtomicFU

Tips: I've forked this project for the book "Kotlin Metaprogramming in Action/深入实践 Kotlin 元编程". It contains some testing code I pushed when writing the book.

Kotlin Beta JetBrains official project GitHub license Maven Central

Note on Beta status: the plugin is in its active development phase and changes from release to release. We do provide a compatibility of atomicfu-transformed artifacts between releases, but we do not provide strict compatibility guarantees on plugin API and its general stability between Kotlin versions.

The idiomatic way to use atomic operations in Kotlin.

Example

Let us declare a top variable for a lock-free stack implementation:

import kotlinx.atomicfu.* // import top-level functions from kotlinx.atomicfu

private val top = atomic<Node?>(null)

Use top.value to perform volatile reads and writes:

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

Use compareAndSet function directly:

if (top.compareAndSet(expect, update)) ...

Use higher-level looping primitives (inline extensions), for example:

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

Use high-level update, updateAndGet, and getAndUpdate, when possible, for idiomatic lock-free code, for example:

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

Declare atomic integers and longs using type inference:

val myInt = atomic(0)    // note: integer initial value
val myLong = atomic(0L)  // note: long initial value

Integer and long atomics provide all the usual getAndIncrement, incrementAndGet, getAndAdd, addAndGet, and etc operations. They can be also atomically modified via += and -= operators.

Dos and Don'ts

private val _foo = atomic<T>(initial) // private atomic, convention is to name it with leading underscore
public var foo: T by _foo            // public delegated property (val/var)

Gradle build setup

Building with Gradle is supported for all platforms.

JVM

You will need Gradle 6.8 or later. Add and apply AtomicFU plugin. It adds all the corresponding dependencies and transformations automatically. See additional configuration if that needs tweaking.

buildscript {
    ext.atomicfu_version = '0.18.3'

    dependencies {
        classpath "org.jetbrains.kotlinx:atomicfu-gradle-plugin:$atomicfu_version"
    }
}

apply plugin: 'kotlinx-atomicfu'

JS

Configure add apply plugin just like for JVM.

Native

This library is available for Kotlin/Native (atomicfu-native). Apply the corresponding plugin just like for JVM.

Atomic references for Kotlin/Native are based on FreezableAtomicReference and every reference that is stored to the previously frozen (shared with another thread) atomic is automatically frozen, too.

Since Kotlin/Native does not generally provide binary compatibility between versions, you should use the same version of Kotlin compiler as was used to build AtomicFU. See gradle.properties in AtomicFU project for its kotlin_version.

Common

If you write a common code that should get compiled or different platforms, add org.jetbrains.kotlinx:atomicfu to your common code dependencies or apply kotlinx-atomicfu plugin that adds this dependency automatically:

dependencies {
    compile "org.jetbrains.kotlinx:atomicfu:$atomicfu_version"
}

IR transformation for Kotlin/JS

There is a new option to turn on IR transformation for Kotlin/JS backend. You can add kotlinx.atomicfu.enableIrTransformation=true to your gradle.properties file in order to enable it.

Here is how transformation is performed for different JS compiler modes with this option enabled:

Additional configuration

To set configuration options you should create atomicfu section in a build.gradle file, like this:

atomicfu {
  dependenciesVersion = '0.18.3'
}

JVM transformation options

To turn off transformation for Kotlin/JVM set option transformJvm to false.

Configuration option jvmVariant defines the Java class that replaces atomics during bytecode transformation. Here are the valid options:

JS transformation options

To turn off transformation for Kotlin/JS set option transformJs to false.

Here are all available configuration options (with their defaults):

atomicfu {
  dependenciesVersion = '0.18.3' // set to null to turn-off auto dependencies
  transformJvm = true // set to false to turn off JVM transformation
  jvmVariant = "FU" // JVM transformation variant: FU,VH, or BOTH 
  jsVariant = "JS" // JS transformation variant: JS or IR
  verbose = false // set to true to be more verbose  
}

Maven build setup

Declare AtomicFU version:

<properties>
     <atomicfu.version>0.18.3</atomicfu.version>
</properties>

Declare provided dependency on the AtomicFU library (the users of the resulting artifact will not have a dependency on AtomicFU library):

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

Configure build steps so that Kotlin compiler puts classes into a different classes-pre-atomicfu directory, which is then transformed to a regular classes directory to be used later by tests and delivery.

<build>
    <plugins>
        <!-- compile Kotlin files to staging directory -->
        <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>
        <!-- transform classes with AtomicFU 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>

Additional features

AtomicFU provides some additional features that you can optionally use.

Arrays of atomic values

You can declare arrays of all supported atomic value types. By default arrays are transformed into the corresponding java.util.concurrent.atomic.Atomic*Array instances.

If you configure variant = "VH" an array will be transformed to plain array using VarHandle to support atomic operations.

val a = atomicArrayOfNulls<T>(size) // similar to Array constructor

val x = a[i].value // read value
a[i].value = x // set value
a[i].compareAndSet(expect, update) // do atomic operations

User-defined extensions on atomics

You can define you own extension functions on AtomicXxx types but they must be inline and they cannot be public and be used outside of the module they are defined in. For example:

@Suppress("NOTHING_TO_INLINE")
private inline fun AtomicBoolean.tryAcquire(): Boolean = compareAndSet(false, true)

Locks

This project includes kotlinx.atomicfu.locks package providing multiplatform locking primitives that require no additional runtime dependencies on Kotlin/JVM and Kotlin/JS with a library implementation for Kotlin/Native.

Note that package kotlinx.atomicfu.locks is experimental explicitly even while atomicfu is experimental itself, meaning that no ABI guarantees are provided whatsoever. API from this package is not recommended to use in libraries that other projects depend on.

Tracing operations

You can debug your tests tracing atomic operations with a special trace object:

private val trace = Trace()
private val current = atomic(0, trace)

fun update(x: Int): Int {           
    // custom trace message
    trace { "calling update($x)" }
    // automatic tracing of modification operations 
    return current.getAndAdd(x)
}

All trace messages are stored in a cyclic array inside trace.

You can optionally set the size of trace's message array and format function. For example, you can add a current thread name to the traced messages:

private val trace = Trace(size = 64) {   
    index, // index of a trace message 
    text   // text passed when invoking trace { text }
    -> "$index: [${Thread.currentThread().name}] $text" 
}

trace is only seen before transformation and completely erased after on Kotlin/JVM and Kotlin/JS.