#azhzx/transaction

///|
test "atomic transfer between accounts" {
  let alice = @transaction.TVar::new(100)
  let bob = @transaction.TVar::new(20)
  @transaction.atomically(txn => {
    let funds = txn.read(alice)
    txn.check(funds >= 30) // block (retry) while funds are short
    txn.write(alice, funds - 30)
    txn.modify(bob, balance => balance + 30)
  })
  inspect(alice.peek(), content="70")
  inspect(bob.peek(), content="50")
}

#Why STM

• Atomicity — every atomically block applies all of its TVar writes together or not at all.
• Isolation — a transaction body sees one consistent snapshot; uncommitted writes of other transactions are never visible.
• Compositional blocking — txn.retry() blocks the current task until something it read changes, and txn.or_else(first, second) combines two blocking operations into one that wakes when either can proceed. No condition variables, no deadlocks, no missed wake-ups.
• Automatic restart — if a read variable is committed by another transaction mid-body, the body is rolled back and re-run on a fresh snapshot. You write straight-line code; the runtime handles interference.

#Packages

#Quick start

moon add azhzx/transaction

///|
import {
  "azhzx/transaction",
  "azhzx/transaction/runner",
} // only if you need async transactions

///|
test "read, write, and peek" {
  let counter = @transaction.TVar::new(0)
  let doubled = @transaction.atomically(txn => {
    txn.modify(counter, x => x + 1)
    txn.read(counter) * 2
  })
  inspect(doubled, content="2")
  inspect(counter.peek(), content="1")
}

#Blocking and choice

///|
test "retry blocks the transaction, not the program" {
  let balance : @transaction.TVar[Int] = @transaction.TVar::new(0)
  try
    @transaction.atomically(txn => {
      txn.check(txn.read(balance) >= 10)
      txn.modify(balance, x => x - 10)
    })
  catch {
    err => assert_true(@transaction.is_retry(err))
  } noraise {
    _ => fail("expected the transaction to block")
  }
  inspect(balance.peek(), content="0")
}

///|
test "or_else tries the first branch, then the second" {
  let urgent : @transaction.TMVar[String] = @transaction.TMVar::new()
  let regular = @transaction.TMVar::full("regular-mail")
  let message = @transaction.atomically(txn => {
    txn.or_else(t => urgent.take(t), t => regular.take(t))
  })
  inspect(message, content="regular-mail")
}

///|
async test "consumer parks until a producer commits" {
  let jobs : @transaction.TQueue[Int] = @transaction.TQueue::new()
  let received = Ref(0)
  @aio.with_task_group(group => {
    group.spawn_bg(() => {
      received.val = @runner.atomically_async(txn => jobs.pop(txn))
    })
    @runner.atomically_async(txn => jobs.push(txn, 42))
  })
  inspect(received.val, content="42")
}

#Ready-made structures

• TMVar[T] — empty-or-full one-slot cell. take retries while empty, put retries while full: a transactional meeting point.
• TQueue[T] — transactional FIFO queue. pop retries while empty; push, try_pop, peek, length, is_empty round it out.

///|
test "queue hands work to a consumer in FIFO order" {
  let jobs = @transaction.TQueue::new()
  @transaction.atomically(txn => {
    jobs.push(txn, "first")
    jobs.push(txn, "second")
  })
  inspect(@transaction.atomically(t => jobs.pop(t)), content="first")
  inspect(
    @transaction.atomically(t => jobs.try_pop(t)) is Some("second"),
    content="true",
  )
}

#Semantics

• Values must be immutable. For Array/Map values, build a fresh copy (items.copy() then mutate the copy) and write it back; never mutate a value obtained from txn.read.
• A body may re-run. Retry, Conflict, and validation failures restart the body with a fresh transaction. Side effects are not rolled back.
• Errors propagate. Any error raised by the body rolls back the writes and reaches the caller unchanged; is_retry distinguishes blocking from failure.
• Transactions do not nest. An atomically call inside a transaction body runs and commits independently; if it invalidates the outer snapshot, the outer transaction restarts automatically.
• Commit ordering. A global commit clock plus per-TVar versions detect stale snapshots in O(read set). Validation and commit happen in one synchronous section, so no interleaving can slip between them.

#Concurrency model

#Development

moon test                            # wasm (default) — includes README and docstring tests
moon test --target native            # native backend
moon bench --target native --release # benchmark suite (see doc/en.md)
moon run examples/showcase           # runnable example (see below)
moon info && moon fmt                # refresh .mbti interfaces and format

#Runnable example

moon run examples/showcase               # wasm
moon run examples/showcase --target native

after transfer: alice=70, bob=50
consumer received: [10, 20, 30]

#License