Atomic

Low-level atomic operations for lock-free concurrent programming. Provides atomic integers and booleans with explicit memory ordering control.

Advanced Feature

Atomic operations are low-level primitives. For most concurrent programming, prefer higher-level abstractions like Actor, Channel, or Parallel.

Memory Ordering

Atomic operations require a memory ordering parameter specified as a keyword. Available orderings (from weakest to strongest):

Ordering	Description
`:relaxed`	No synchronization. Only guarantees atomicity.
`:acquire`	Prevents reads/writes from being reordered before this operation.
`:release`	Prevents reads/writes from being reordered after this operation.
`:acq-rel`	Combines acquire and release semantics.
`:seq-cst`	Sequential consistency. Strongest ordering.

AtomicInt

64-bit atomic integer operations.

Atomic.int-new

Int -> Int

Creates a new atomic integer with the given initial value. Returns an ID used to reference it.

counter = Atomic.int-new 0

Atomic.int-load

Int -> Keyword -> Int

Atomically loads the value with the specified memory ordering.

value = Atomic.int-load counter :seq-cst

Atomic.int-store

Int -> Int -> Keyword -> ()

Atomically stores a value with the specified memory ordering.

Atomic.int-store counter 42 :release

Atomic.int-swap

Int -> Int -> Keyword -> Int

Atomically swaps the value, returning the old value.

Atomic.int-compare-swap

Int -> Int -> Int -> Keyword -> Keyword -> Option Int

Compare-and-swap operation. If current value equals expected, replaces with new value. Returns Some old on success, None on failure. Takes success and failure memory orderings.

# Increment only if current value is 5
match Atomic.int-compare-swap counter 5 6 :seq-cst :relaxed
  | Some old -> println "Swapped from ${old}"
  | None -> println "Value was not 5"

Atomic.int-fetch-add / int-fetch-sub

Int -> Int -> Keyword -> Int

Atomically adds/subtracts and returns the previous value.

# Atomic increment, returns old value
old = Atomic.int-fetch-add counter 1 :seq-cst

Atomic.int-fetch-and / int-fetch-or / int-fetch-xor

Int -> Int -> Keyword -> Int

Atomic bitwise operations, returning the previous value.

AtomicBool

Atomic boolean operations.

Atomic.bool-new

Bool -> Int

Creates a new atomic boolean with the given initial value.

flag = Atomic.bool-new false

Atomic.bool-load

Int -> Keyword -> Bool

Atomically loads the boolean value.

Atomic.bool-store

Int -> Bool -> Keyword -> ()

Atomically stores a boolean value.

Atomic.bool-store flag true :release

Atomic.bool-swap

Int -> Bool -> Keyword -> Bool

Atomically swaps the boolean value, returning the old value.

Atomic.bool-compare-swap

Int -> Bool -> Bool -> Keyword -> Keyword -> Option Bool

Boolean compare-and-swap operation.

Fences

Memory fence operations for advanced synchronization.

Atomic.fence

Keyword -> ()

Establishes a memory fence with the specified ordering. Prevents memory reordering across the fence.

Atomic.fence :acquire

Atomic.compiler-fence

Keyword -> ()

Compiler-only fence. Prevents the compiler from reordering operations but does not affect CPU reordering.

Atomic.spin-hint

() -> ()

Hints to the CPU that this is a spin-loop, potentially reducing power consumption.

# Spin until flag is set
while not (Atomic.bool-load flag :acquire)
  Atomic.spin-hint()