std/concurrent
std/concurrent — locks, channels, atomics and synchronization aids.
Handle-backed classes: every class carries a single handle : i64 — the
address of the boxed Rust value behind it, widened to i64, with 0 for
none — except Thread, whose handle is a key in the task table of the
thread that started it. Each exposes its construction parameters through an
explicit constructor(...). Method calls pass the handle as self to the
matching __axle_stdlib_concurrent_<Class>_<m> native binding. Async is
the one static facade: it holds no handle.
The locks and aids below belong to the task, not the thread: the holder
of a lock is the running task, and a contended wait parks that task while
its carrier runs the others.! InterruptedException is the declared error channel of every primitive
that waits. The runtime cannot interrupt a waiter — a parked task wakes on
its own signal, on the close of what it waits on, or not at all — so the
channel is never entered by interruption; it carries the runtime's own
threading faults (a closed channel, a cancelled operation).
C class Async
Static facade for the async (coroutine) world. Async::sleep(ms)
mints a Future<void> resolving after ms milliseconds;awaiting it parks the coroutine cooperatively on the event loop
(other machines keep running) — unlike the prelude sleep(ms) ofstd/sys, which pauses the whole frame that calls it and so is refused in
an async fn. Async::all(futures) (or await all futures)
joins a Future<T>[] into one storable Future<T[]> handle.
Methods
| Type | Method and description |
|---|---|
| sleep(ms : i64) : Future<void> A Future<void> resolving after ms milliseconds — the eventloop's base awaitable. await Async::sleep(ms) is a cooperativeyield, not a thread block. |
Method detail
#sleep
A Future<void> resolving after ms milliseconds — the event
loop's base awaitable. await Async::sleep(ms) is a cooperative
yield, not a thread block.
ms delay before the timer resolves, in milliseconds.C class Thread
A unit of work that owns a platform thread rather than a slot in the
task pool: true parallelism, room for a deep call chain or a blocking
syscall. Thread::run(f, args…) starts it, or Thread::create(f, args…)
prepares it and run() starts it; join() waits for it and re-raises
whatever f threw, as if the body had thrown at the join; isAlive()
is a non-blocking liveness peek. The entry is a named function or static
method, not a closure.
A Thread is one-shot and is never cancelled: a second join throwsIllegalStateException, and dropping the handle detaches the thread —
its work still happens, only the ability to wait for it is gone.
Methods
| Type | Method and description |
|---|---|
| run(self) : void Start the thread Thread::create(f, args…) prepared. Thread::runcreates and starts in one call; create then run() lets a programhold the handle before the body is running. Throws IllegalStateException on a second run(), or on a handle that namesno created thread; a join() before run() throws too. |
| join(self) : void Wait until the thread's body has finished — a task parks, a plain frame blocks — then re-raise any exception the body captured. Throws IllegalStateException when the thread was already joined, was createdand never run(), or was started on another thread. |
| isAlive(self) : bool true while the body is still running. Never blocks. |
Method detail
#run
Start the thread Thread::create(f, args…) prepared. Thread::run
creates and starts in one call; create then run() lets a program
hold the handle before the body is running. ThrowsIllegalStateException on a second run(), or on a handle that names
no created thread; a join() before run() throws too.
#join
Wait until the thread's body has finished — a task parks, a plain frame
blocks — then re-raise any exception the body captured. ThrowsIllegalStateException when the thread was already joined, was created
and never run(), or was started on another thread.
#isAlive
true while the body is still running. Never blocks.
C class ReentrantLock
Mutual-exclusion lock that the task holding it may re-acquire.
Methods take/release explicitly because Axle has no RAII guards.
Methods
| Type | Method and description |
|---|---|
| lock(self) : void Acquire the lock, blocking until it is available. |
| tryLock(self) : bool Try to acquire the lock without blocking. |
| unlock(self) : void Release one acquisition; must be balanced with lock / tryLock.Throws IllegalStateException when the caller holds no acquisition:the lock stays with whoever does. |
| isLocked(self) : bool true if the lock is currently held by any task. |
Method detail
#lock
Acquire the lock, blocking until it is available.
#tryLock
Try to acquire the lock without blocking.
true if the lock was acquired, false if held elsewhere.#unlock
Release one acquisition; must be balanced with lock / tryLock.
Throws IllegalStateException when the caller holds no acquisition:
the lock stays with whoever does.
#isLocked
true if the lock is currently held by any task.
C class UnboundedChannel
Channel with no capacity bound — send never blocks on a full
queue.
Methods
| Type | Method and description |
|---|---|
| send(self, value : i32) : void Enqueue a value; never blocks on capacity (the queue is unbounded), so it never parks the caller either. |
| receive(self) : i32 Dequeue the next value, blocking until one is available. |
| trySend(self, value : i32) : bool Non-blocking enqueue. |
| tryReceive(self) : i32 Non-blocking dequeue; returns immediately whether or not a value is ready. |
| close(self) : void Close the channel; subsequent sends fail and pending receives drain. |
Method detail
#send
Enqueue a value; never blocks on capacity (the queue is unbounded), so
it never parks the caller either.
value the i32 payload to enqueue.#receive
Dequeue the next value, blocking until one is available.
#trySend
Non-blocking enqueue.
value the i32 payload to enqueue.true unless the channel is closed.#tryReceive
Non-blocking dequeue; returns immediately whether or not a value is ready.
#close
Close the channel; subsequent sends fail and pending receives drain.
C class BoundedChannel
Channel with a fixed capacity — send blocks once the queue is
full, giving back-pressure to the producer.
Constructors
| Type | Method and description |
|---|---|
| constructor(capacity : i32) |
Method detail
#constructor
capacity maximum number of buffered values before sendblocks the producer. A capacity below one is read
as one: a channel that buffers nothing would need
a sender and a receiver to meet inside the same
call, and this channel hands off through a queue.
Methods
| Type | Method and description |
|---|---|
| send(self, value : i32) : void Enqueue a value, blocking while the queue is full (back-pressure). |
| receive(self) : i32 Dequeue the next value, blocking until one is available. |
| trySend(self, value : i32) : bool Non-blocking enqueue. |
| tryReceive(self) : i32 Non-blocking dequeue; returns immediately whether or not a value is ready. |
| close(self) : void Close the channel; subsequent sends fail and pending receives drain. |
Method detail
#send
Enqueue a value, blocking while the queue is full (back-pressure).
value the i32 payload to enqueue.#receive
Dequeue the next value, blocking until one is available.
#trySend
Non-blocking enqueue.
value the i32 payload to enqueue.true if buffered, false if the queue is full or closed.#tryReceive
Non-blocking dequeue; returns immediately whether or not a value is ready.
#close
Close the channel; subsequent sends fail and pending receives drain.
C class AtomicI32
32-bit atomic counter with lock-free get / set / increment /
add, plus compare-and-swap and exchange. A reader and a writer on
different threads observe a single indivisible transition.
Constructors
| Type | Method and description |
|---|---|
| constructor(initial : i32) |
Method detail
#constructor
initial starting value of the counter.Methods
| Type | Method and description |
|---|---|
| get(self) : i32 Atomically read the current value. |
| set(self, newValue : i32) : void Atomically store newValue. |
| incrementAndGet(self) : i32 Atomically add one. |
| decrementAndGet(self) : i32 Atomically subtract one. |
| addAndGet(self, delta : i32) : i32 Atomically add delta. |
| compareAndSet(self, expected : i32, update : i32) : bool Atomically set the value to update only if it currently equalsexpected (compare-and-swap). |
| swap(self, newValue : i32) : i32 Atomically store newValue and return the value it replaced. |
| getAcquire(self) : i32 Like get, ordered acquire instead of sequentially consistent:when this load observes a value stored with setRelease, everythingthe storing thread wrote before that store is visible after the load. |
| setRelease(self, newValue : i32) : void Like set, ordered release instead of sequentially consistent:everything this thread wrote before the store is visible to a thread that observes the value with getAcquire. |
| compareAndSetAcqRel(self, expected : i32, update : i32) : bool Like compareAndSet, ordered acquire-release instead ofsequentially consistent: a successful swap both publishes what this thread wrote and observes what the previous owner wrote. |
Method detail
#get
Atomically read the current value.
#set
Atomically store newValue.
newValue the i32 value to publish to all threads.#incrementAndGet
Atomically add one.
#decrementAndGet
Atomically subtract one.
#addAndGet
Atomically add delta.
delta signed amount to add (negative to subtract).#compareAndSet
Atomically set the value to update only if it currently equalsexpected (compare-and-swap).
expected value the counter must currently hold for the swap to occur.update value to store when the witnessed value matches expected.true if the swap happened, false if the witnessed valuediffered from
expected.#swap
Atomically store newValue and return the value it replaced.
newValue the i32 value to publish to all threads.#getAcquire
Like get, ordered acquire instead of sequentially consistent:
when this load observes a value stored with setRelease, everything
the storing thread wrote before that store is visible after the load.
#setRelease
Like set, ordered release instead of sequentially consistent:
everything this thread wrote before the store is visible to a
thread that observes the value with getAcquire.
newValue the i32 value to publish.#compareAndSetAcqRel
Like compareAndSet, ordered acquire-release instead of
sequentially consistent: a successful swap both publishes what
this thread wrote and observes what the previous owner wrote.
expected value the counter must currently hold for the swap to occur.update value to store when the witnessed value matches expected.true if the swap happened.C class AtomicI64
64-bit atomic counter. Same shape as AtomicI32, including its
compare-and-swap and exchange operations; different width.
Constructors
| Type | Method and description |
|---|---|
| constructor(initial : i64) |
Method detail
#constructor
initial starting value of the counter.Methods
| Type | Method and description |
|---|---|
| get(self) : i64 Atomically read the current value. |
| set(self, newValue : i64) : void Atomically store newValue. |
| incrementAndGet(self) : i64 Atomically add one. |
| decrementAndGet(self) : i64 Atomically subtract one. |
| addAndGet(self, delta : i64) : i64 Atomically add delta. |
| compareAndSet(self, expected : i64, update : i64) : bool Atomically set the value to update only if it currently equalsexpected (compare-and-swap). |
| swap(self, newValue : i64) : i64 Atomically store newValue and return the value it replaced. |
| getAcquire(self) : i64 Like get, ordered acquire instead of sequentially consistent:when this load observes a value stored with setRelease, everythingthe storing thread wrote before that store is visible after the load. |
| setRelease(self, newValue : i64) : void Like set, ordered release instead of sequentially consistent:everything this thread wrote before the store is visible to a thread that observes the value with getAcquire. |
| compareAndSetAcqRel(self, expected : i64, update : i64) : bool Like compareAndSet, ordered acquire-release instead ofsequentially consistent: a successful swap both publishes what this thread wrote and observes what the previous owner wrote. |
Method detail
#get
Atomically read the current value.
#set
Atomically store newValue.
newValue the i64 value to publish to all threads.#incrementAndGet
Atomically add one.
#decrementAndGet
Atomically subtract one.
#addAndGet
Atomically add delta.
delta signed amount to add (negative to subtract).#compareAndSet
Atomically set the value to update only if it currently equalsexpected (compare-and-swap).
expected value the counter must currently hold for the swap to occur.update value to store when the witnessed value matches expected.true if the swap happened, false if the witnessed valuediffered from
expected.#swap
Atomically store newValue and return the value it replaced.
newValue the i64 value to publish to all threads.#getAcquire
Like get, ordered acquire instead of sequentially consistent:
when this load observes a value stored with setRelease, everything
the storing thread wrote before that store is visible after the load.
#setRelease
Like set, ordered release instead of sequentially consistent:
everything this thread wrote before the store is visible to a
thread that observes the value with getAcquire.
newValue the i64 value to publish.#compareAndSetAcqRel
Like compareAndSet, ordered acquire-release instead of
sequentially consistent: a successful swap both publishes what
this thread wrote and observes what the previous owner wrote.
expected value the counter must currently hold for the swap to occur.update value to store when the witnessed value matches expected.true if the swap happened.C class AtomicBoolean
Boolean flag with atomic load / store / CAS. Backed by anAtomicBool on the Rust side so a writer and a reader on
different threads observe a single-step transition.
Constructors
| Type | Method and description |
|---|---|
| constructor(initial : bool) |
Method detail
#constructor
initial starting value of the flag.Methods
| Type | Method and description |
|---|---|
| get(self) : bool Atomically read the current value. |
| set(self, newValue : bool) : void Atomically store newValue. |
| compareAndSet(self, expected : bool, update : bool) : bool Atomically set the value to update only if it currently equalsexpected (compare-and-swap). |
| getAcquire(self) : bool Like get, ordered acquire instead of sequentially consistent:when this load observes a flag stored with setRelease, everythingthe storing thread wrote before that store is visible after the load. |
| setRelease(self, newValue : bool) : void Like set, ordered release instead of sequentially consistent:everything this thread wrote before the store is visible to a thread that observes the flag with getAcquire. |
| compareAndSetAcqRel(self, expected : bool, update : bool) : bool Like compareAndSet, ordered acquire-release instead ofsequentially consistent: a successful swap both publishes what this thread wrote and observes what the previous owner wrote. |
Method detail
#get
Atomically read the current value.
#set
Atomically store newValue.
newValue the bool flag value to publish to all threads.#compareAndSet
Atomically set the value to update only if it currently equalsexpected (compare-and-swap).
expected value the flag must currently hold for the swap to occur.update value to store when the witnessed value matches expected.true if the swap happened, false if the witnessed valuediffered from
expected.#getAcquire
Like get, ordered acquire instead of sequentially consistent:
when this load observes a flag stored with setRelease, everything
the storing thread wrote before that store is visible after the load.
#setRelease
Like set, ordered release instead of sequentially consistent:
everything this thread wrote before the store is visible to a
thread that observes the flag with getAcquire.
newValue the bool flag value to publish.#compareAndSetAcqRel
Like compareAndSet, ordered acquire-release instead of
sequentially consistent: a successful swap both publishes what
this thread wrote and observes what the previous owner wrote.
expected value the flag must currently hold for the swap to occur.update value to store when the witnessed value matches expected.true if the swap happened.C class CountDownLatch
CountDownLatch — single-shot barrier. Construct with an
initial count, countDown() decrements, waitFor() blocks
until the count reaches zero.
Constructors
| Type | Method and description |
|---|---|
| constructor(count : i32) A latch that opens after count count-downs. A count at or below zerois already open — a negative count asks for "no count-downs at all", the same reading Semaphore gives a negative permit count. |
Method detail
#constructor
A latch that opens after count count-downs. A count at or below zero
is already open — a negative count asks for "no count-downs at all",
the same reading Semaphore gives a negative permit count.
count number of countDown() calls before the latch opensMethods
| Type | Method and description |
|---|---|
| countDown(self) : void Decrement the count by one; releases waiters once it reaches zero. |
| waitFor(self) : void Block until the count reaches zero. await is reserved by theasync/await sugar; the latch primitive uses waitFor (matchesCondition.waitFor). |
| waitForWithTimeout(self, millis : i64) : bool Block until the count reaches zero or the deadline elapses. |
| getCount(self) : i32 The current remaining count. |
Method detail
#countDown
Decrement the count by one; releases waiters once it reaches zero.
#waitFor
Block until the count reaches zero. await is reserved by the
async/await sugar; the latch primitive uses waitFor (matchesCondition.waitFor).
#waitForWithTimeout
Block until the count reaches zero or the deadline elapses.
millis maximum time to wait, in milliseconds.true if the count reached zero, false if it timed out.#getCount
The current remaining count.
C class ReadWriteLock
ReadWriteLock — readers can run concurrently, the writer
holds exclusive access, and a reader arriving while a writer
waits queues behind it. Backed by the runtime's task-aware
read-write lock: a contended acquire parks the task, not its
thread. Methods take/release explicitly because Axle has no RAII
guards.
Methods
| Type | Method and description |
|---|---|
| readLock(self) : void Acquire a shared read lock, blocking while a writer holds it or waits for it. A caller that already holds a read lock takes another at once. |
| readUnlock(self) : void Release one of the caller's shared read acquisitions — the calling task's, or outside any task the calling thread's. Throws IllegalStateException when the caller holds none; another reader'sacquisition is never released in its place. |
| writeLock(self) : void Acquire the exclusive write lock, blocking until no reader or writer holds it. |
| writeUnlock(self) : void Release the exclusive write lock. Throws IllegalStateException whenthe caller does not hold it. |
| tryReadLock(self) : bool Try to acquire a shared read lock without blocking. |
| tryWriteLock(self) : bool Try to acquire the exclusive write lock without blocking. |
Method detail
#readLock
Acquire a shared read lock, blocking while a writer holds it or waits
for it. A caller that already holds a read lock takes another at once.
#readUnlock
Release one of the caller's shared read acquisitions — the calling
task's, or outside any task the calling thread's. ThrowsIllegalStateException when the caller holds none; another reader's
acquisition is never released in its place.
#writeLock
Acquire the exclusive write lock, blocking until no reader or writer holds it.
#writeUnlock
Release the exclusive write lock. Throws IllegalStateException when
the caller does not hold it.
#tryReadLock
Try to acquire a shared read lock without blocking.
true if acquired, false if a writer holds the lock or waits for it.#tryWriteLock
Try to acquire the exclusive write lock without blocking.
true if acquired, false if any reader or writer holds it.C class Semaphore
Semaphore — counting permit pool. acquire() blocks when
no permit is available; release() returns one to the pool.
Constructors
| Type | Method and description |
|---|---|
| constructor(permits : i32) |
Method detail
#constructor
permits initial number of permits in the pool.Methods
| Type | Method and description |
|---|---|
| acquire(self) : void Take one permit, blocking until one becomes available. |
| tryAcquire(self) : bool Try to take one permit without blocking. |
| release(self) : void Return one permit to the pool, potentially unblocking a waiter. |
| availablePermits(self) : i32 The number of permits currently available (a snapshot). |
Method detail
#acquire
Take one permit, blocking until one becomes available.
#tryAcquire
Try to take one permit without blocking.
true if a permit was taken, false if none were available.#release
Return one permit to the pool, potentially unblocking a waiter.
#availablePermits
The number of permits currently available (a snapshot).
T trait Condition
Wait/notify primitive paired with a lock: a task parks inwaitFor until another signals the condition.
| Type | Method and description |
|---|---|
| waitFor(self) : void Atomically release the lock and block until signalled, then re-acquire the lock before returning. |
| waitForMillis(self, millis : i64) : void Like waitFor, but also returns once the deadline elapses. |
| signal(self) : void Wake one task waiting on this condition. |
| signalAll(self) : void Wake all tasks waiting on this condition. |
Method detail
#waitFor
Atomically release the lock and block until signalled, then
re-acquire the lock before returning.
#waitForMillis
Like waitFor, but also returns once the deadline elapses.
millis maximum time to wait, in milliseconds.#signal
Wake one task waiting on this condition.
#signalAll
Wake all tasks waiting on this condition.
T trait Channel
Thread-safe message queue carrying i32 values. send / receive
block; trySend / tryReceive are the non-blocking variants.
| Type | Method and description |
|---|---|
| send(self, value : i32) : void Enqueue a value, blocking if the channel is bounded and full. |
| receive(self) : i32 Dequeue the next value, blocking until one is available. |
| trySend(self, value : i32) : bool Non-blocking enqueue. |
| tryReceive(self) : i32 Non-blocking dequeue; returns immediately whether or not a value is ready. |
| close(self) : void Close the channel; subsequent sends fail and pending receives drain. |
Method detail
#send
Enqueue a value, blocking if the channel is bounded and full.
#receive
Dequeue the next value, blocking until one is available.
#trySend
Non-blocking enqueue.
true if the value was accepted, false if the channelis full or closed.
#tryReceive
Non-blocking dequeue; returns immediately whether or not a value
is ready.
#close
Close the channel; subsequent sends fail and pending receives drain.