API Reference

fn byId(id: Int): AtomicInt

Open the shared cell registered under id, creating it at 0 if this is the first use of that id.

id — registry slot shared with other threads. Pick an id no other code in the program uses; a number reused by a different primitive names a different object.

returns — handle to the cell.

fn cas(expected: Int, newVal: Int): Bool

Compare-and-swap: store newVal only when the cell holds expected. The comparison and the store are one indivisible step, so the call either swaps or reports that another thread got there first. When it returns false the cell is left alone, so read it again to see what the current value is.

expected — value that must be present for the swap to happen.

newVal — value to store on match.

returns — true when the swap happened.

import { AtomicInt } from "@std/sync";

let slot = AtomicInt.byId(8);
slot.set(1);
print(slot.cas(1, 2), slot.get());
print(slot.cas(1, 3), slot.get());

fn fetchAdd(delta: Int): Int

Add delta to the cell and report the value that was there first. The read and the write are one indivisible step, so several threads can add to the same cell without losing updates. This is the building block for counters, unique id handouts, and work queues.

delta — amount to add. Negative values subtract.

returns — value before the add.

import { AtomicInt } from "@std/sync";

let a = AtomicInt.byId(1);
a.set(10);
print(a.fetchAdd(5), a.get());

fn get(): Int

Read the cell.

returns — current value, as stored by the most recent `set` or atomic update that this thread can observe.

import { AtomicInt } from "@std/sync";

let a = AtomicInt.byId(11);
a.set(41);
print(a.get() + 1);

fn set(val: Int)

Store a new value, replacing whatever was there.

val — value to store. Written in full, so a reader never sees a half-updated value.

fn byId(id: Int, count: Int): Barrier

Open the shared barrier registered under id. The first party to arrive sets the trip threshold, so every thread must build its handle with the same count. The gate is reusable: each trip resets it for the next generation.

id — registry slot shared with other threads. Pick an id no other code in the program uses; a number reused by a different primitive names a different object.

count — parties required to trip the gate, greater than 0. Every handle for this id should pass the same number.

returns — handle to the barrier.

throws — when count is 0 or negative, with a message naming the bad value. The throw runs in a function that is not declared `throws`, so an enclosing `try` does not intercept it: the program stops with `Uncaught exception` and exit status 1. Validate the count before calling when it comes from outside the program.

import { Barrier } from "@std/sync";

let solo = Barrier.byId(61, 1);
print("first generation:", solo.wait());
print("gate resets:", solo.wait());

fn wait(): Bool

Block until count parties arrive. All count parties park; the count-th arrival releases the whole generation at once, resets the gate, and returns true for exactly one leader (false for the rest). The leader is whichever thread arrived last, so use the return value to elect one thread for per-generation work such as merging results.

returns — true for the single party whose arrival tripped the gate, false for the others. Every party sees the same generation release.

import { Barrier } from "@std/sync";

let solo = Barrier.byId(61, 1);
print("leader:", solo.wait());

fn byId(id: Int): Channel

Open the shared queue registered under id, creating it empty on first use.

id — registry slot shared with other threads. Pick an id no other code in the program uses; a number reused by a different primitive names a different object.

returns — handle to the queue.

fn close(): Void

Drop the queue, releasing anything still queued. Queued heap payloads are freed here. The id stays registered and a later `send` on the same handle works again, so this releases buffered values without unregistering the queue. A thread parked in `recv` is not woken.

fn len(): Int

Queued message count.

returns — number of waiting messages. Advisory only: another thread may enqueue or dequeue right after the read, so do not build a decision on it that `tryRecv` has to undo.

fn recv(): Any

Dequeue the oldest value, blocking until one arrives. Parks the calling thread while the queue is empty. `close` does not release it, so a consumer waiting here needs a `send` from elsewhere, or a `Condvar` with a timeout to bound the wait.

returns — the value as Any; cast before use.

import { Channel, Thread } from "@std/sync";

fn produce(): Int {
let inbox = Channel.byId(3);
inbox.send("payload");
return 1;
}

let inbox = Channel.byId(3);
let worker = Thread.spawn(produce);
print("received:", inbox.recv());
print("worker done:", worker.join().unwrap());

fn send(val: Any): Void

Enqueue a value, retaining heap payloads for the receiver. The call never blocks, whatever the queue length. Values come out in the order they went in.

val — Int, Float, String, Array, or object. A heap payload is retained on the way in, so the receiver owns it after `recv`.

import { Channel } from "@std/sync";

let jobs = Channel.byId(9);
jobs.send(7);
jobs.send(8);
print("queued:", jobs.len());
print("took:", jobs.tryRecv());

fn tryRecv(): Int

Dequeue the oldest value only if one is already queued. The polling counterpart to `recv`: it reports absence in the return value instead of parking, so a loop over it never blocks.

returns — the value as Any when one was ready, or -1 when the queue was empty. Test against -1, not against a boolean, and narrow a real value with an `is` check before using it.

import { Channel } from "@std/sync";

let jobs = Channel.byId(9);
jobs.send(7);
print(jobs.tryRecv(), jobs.tryRecv());

fn byId(id: Int): Condvar

Open the shared condvar registered under id, with no waiters on first use.

id — registry slot shared with other threads. Pick an id no other code in the program uses; a number reused by a different primitive names a different object.

returns — handle to the condvar.

fn notifyAll(): Void

Wake every parked waiter, if any. Does nothing when no thread is waiting. Use it when several waiters share a condition and a change releases all of them at once.

import { Condvar, Mutex } from "@std/sync";

let m = Mutex.byId(51);
let c = Condvar.byId(51);
m.lock();
c.notifyAll();
m.unlock();

fn notifyOne(): Void

Wake one parked waiter, if any. Does nothing when no thread is waiting, so a notify sent too early is lost. The woken thread holds its mutex again by the time `wait` returns.

fn wait(m: Mutex): Void

Sleep until notified, releasing the mutex while parked. The mutex is released before the thread sleeps and re-taken before this returns, so the caller still holds it on the way out. A notify that arrives before the sleep is missed, which is why the condition has to be re-tested in a loop after waking.

m — mutex held by the caller. The call aborts the program when it is not held.

import { Condvar, Mutex } from "@std/sync";

let m = Mutex.byId(51);
let c = Condvar.byId(51);
m.lock();
c.notifyAll();
m.unlock();

fn waitTimeout(m: Mutex, millis: Int): Bool

Sleep until notified or the timeout elapses, whichever comes first. Releases and re-takes the mutex the same way `wait` does, so a notifying thread can make progress while this thread sleeps. Useful for a poll loop that must not block forever, and for giving up on a thread that never arrives.

m — mutex held by the caller. The call aborts the program when it is not held.

millis — maximum park time. A negative value is treated as 0.

returns — true when woken by a notify, false on timeout.

import { Condvar, Mutex } from "@std/sync";

let m = Mutex.byId(51);
let c = Condvar.byId(51);
m.lock();
print("woken:", c.waitTimeout(m, 30));
m.unlock();

fn byId(id: Int): Mutex

Open the shared mutex registered under id, unlocked on first use.

id — registry slot shared with other threads. Pick an id no other code in the program uses; a number reused by a different primitive names a different object.

returns — handle to the mutex.

fn lock(): Void

Acquire the lock, blocking until it is free. Parks the calling thread while another thread holds the lock. Deadlocks if the same thread already holds it, or if two threads take two locks in opposite orders.

import { Mutex } from "@std/sync";

let m = Mutex.byId(31);
m.lock();
m.unlock();
print(m.tryLock());
m.unlock();

fn tryLock(): Bool

Acquire the lock only when it is free, never blocking. The polling counterpart to `lock`, for code that would rather give up a lock than wait for it. It reports the outcome in the return value, so a failed attempt leaves the lock untouched.

returns — true when the lock was taken by this call, false when it was already held. Release the lock only when this returns true.

import { Mutex } from "@std/sync";

let a = Mutex.byId(31);
let b = Mutex.byId(31);
a.lock();
print(b.tryLock());
a.unlock();

fn unlock(): Void

Release a held mutex and wake one thread waiting in `lock`. Aborts the program when the lock is not held, so pair every `lock` with exactly one `unlock`.

fn byId(id: Int): RwLock

Open the shared rwlock registered under id, fully released on first use.

id — registry slot shared with other threads. Pick an id no other code in the program uses; a number reused by a different primitive names a different object.

returns — handle to the rwlock.

fn readLock(): Void

Acquire shared read access, blocking only while a writer holds the lock. Any number of readers hold the lock at the same time, so readers never wait for each other. Must be released with one `readUnlock`.

fn readUnlock(): Void

Release shared read access. Wakes a waiting writer once the last reader is out. Aborts the program when no read access is held.

fn tryReadLock(): Bool

Take read access only when no writer is active, never blocking. Succeeds while readers hold the lock, since readers do not exclude each other. The polling counterpart to `readLock`.

returns — true when read access was taken by this call. Release it with `readUnlock` only when this returns true.

import { RwLock } from "@std/sync";

let r = RwLock.byId(41);
r.writeLock();
print(r.tryReadLock());
r.writeUnlock();

fn tryWriteLock(): Bool

Take write access only when the lock is completely free, never blocking. Fails while any reader or writer holds the lock. The polling counterpart to `writeLock`.

returns — true when write access was taken by this call. Release it with `writeUnlock` only when this returns true.

import { RwLock } from "@std/sync";

let r = RwLock.byId(41);
print(r.tryWriteLock());
r.writeUnlock();

fn writeLock(): Void

Acquire exclusive write access, blocking until no reader and no writer hold the lock. Parks the calling thread for as long as any reader is active. Must be released with one `writeUnlock`.

fn writeUnlock(): Void

Release exclusive write access and wake everyone waiting on the lock. Aborts the program when write access is not held.

fn byId(id: Int): Thread

Open a handle to an existing native thread slot. `Thread.spawn` is an intrinsic and the compiler claims every `Thread.<name>` call, so this method is not reachable from Rasmalai source: the compiler answers `unknown Thread.byId` before the class body is consulted. A handle is a plain wrapper around a slot id, and the id is readable from a spawned handle's `id` field.

id — slot id returned by a previous spawn.

returns — handle to the thread.

fn join(): Result<Any, String>

Wait for the thread to finish, up to 30 seconds. Output the thread produced is merged into this thread's output when it is joined. The handle is consumed, so a second `join` on the same handle reports a dead thread.

returns — Ok(value) with the thread return, Err(message) on failure. The message is `uncaught <value>` for a body that threw, `Thread panicked` for a panic, the 30 second timeout note for a thread that ran too long, `join of dead thread N` for a reused handle, and a spawn failure note when the thread never started.

import { Thread } from "@std/sync";

fn worker(): Int {
return 40 + 2;
}
let workers: Array<Thread> = [];
workers.push(Thread.spawn(worker));
print(workers[0].join().unwrap());