Axle v0.22.0
Package

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) of
std/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

TypeMethod and description
Future<void>
sleep(ms : i64) : Future<void> 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.

Method detail

#sleep

sleep(ms : i64) : Future<void>

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.

Parameters
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 throws
IllegalStateException, and dropping the handle detaches the thread —
its work still happens, only the ability to wait for it is gone.

Methods

TypeMethod and description
void
run(self) : void 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. Throws
IllegalStateException on a second run(), or on a handle that names
no created thread; a join() before run() throws too.
void
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 created
and never run(), or was started on another thread.
bool
isAlive(self) : bool true while the body is still running. Never blocks.

Method detail

#run

run(self) : void ! IllegalStateException

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. Throws
IllegalStateException on a second run(), or on a handle that names
no created thread; a join() before run() throws too.

#join

join(self) : void ! IllegalStateException

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 created
and never run(), or was started on another thread.

#isAlive

isAlive(self) : bool

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

TypeMethod and description
void
lock(self) : void Acquire the lock, blocking until it is available.
bool
tryLock(self) : bool Try to acquire the lock without blocking.
void
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.
bool
isLocked(self) : bool true if the lock is currently held by any task.

Method detail

#lock

lock(self) : void

Acquire the lock, blocking until it is available.

#tryLock

tryLock(self) : bool

Try to acquire the lock without blocking.

Returns true if the lock was acquired, false if held elsewhere.

#unlock

unlock(self) : void ! IllegalStateException

Release one acquisition; must be balanced with lock / tryLock.
Throws IllegalStateException when the caller holds no acquisition:
the lock stays with whoever does.

#isLocked

isLocked(self) : bool

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

TypeMethod and description
void
send(self, value : i32) : void Enqueue a value; never blocks on capacity (the queue is unbounded), so
it never parks the caller either.
i32
receive(self) : i32 Dequeue the next value, blocking until one is available.
bool
trySend(self, value : i32) : bool Non-blocking enqueue.
i32
tryReceive(self) : i32 Non-blocking dequeue; returns immediately whether or not a value is ready.
void
close(self) : void Close the channel; subsequent sends fail and pending receives drain.

Method detail

#send

send(self, value : i32) : void ! InterruptedException

Enqueue a value; never blocks on capacity (the queue is unbounded), so
it never parks the caller either.

Parameters
value the i32 payload to enqueue.

#receive

receive(self) : i32 ! InterruptedException

Dequeue the next value, blocking until one is available.

#trySend

trySend(self, value : i32) : bool

Non-blocking enqueue.

Parameters
value the i32 payload to enqueue.
Returns true unless the channel is closed.

#tryReceive

tryReceive(self) : i32

Non-blocking dequeue; returns immediately whether or not a value is ready.

#close

close(self) : void ! IOException

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

TypeMethod and description
constructor(capacity : i32)

Method detail

#constructor

constructor(capacity : i32)

Parameters
capacity maximum number of buffered values before send
blocks 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

TypeMethod and description
void
send(self, value : i32) : void Enqueue a value, blocking while the queue is full (back-pressure).
i32
receive(self) : i32 Dequeue the next value, blocking until one is available.
bool
trySend(self, value : i32) : bool Non-blocking enqueue.
i32
tryReceive(self) : i32 Non-blocking dequeue; returns immediately whether or not a value is ready.
void
close(self) : void Close the channel; subsequent sends fail and pending receives drain.

Method detail

#send

send(self, value : i32) : void ! InterruptedException

Enqueue a value, blocking while the queue is full (back-pressure).

Parameters
value the i32 payload to enqueue.

#receive

receive(self) : i32 ! InterruptedException

Dequeue the next value, blocking until one is available.

#trySend

trySend(self, value : i32) : bool

Non-blocking enqueue.

Parameters
value the i32 payload to enqueue.
Returns true if buffered, false if the queue is full or closed.

#tryReceive

tryReceive(self) : i32

Non-blocking dequeue; returns immediately whether or not a value is ready.

#close

close(self) : void ! IOException

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

TypeMethod and description
constructor(initial : i32)

Method detail

#constructor

constructor(initial : i32)

Parameters
initial starting value of the counter.

Methods

TypeMethod and description
i32
get(self) : i32 Atomically read the current value.
void
set(self, newValue : i32) : void Atomically store newValue.
i32
incrementAndGet(self) : i32 Atomically add one.
i32
decrementAndGet(self) : i32 Atomically subtract one.
i32
addAndGet(self, delta : i32) : i32 Atomically add delta.
bool
compareAndSet(self, expected : i32, update : i32) : bool Atomically set the value to update only if it currently equals
expected (compare-and-swap).
i32
swap(self, newValue : i32) : i32 Atomically store newValue and return the value it replaced.
i32
getAcquire(self) : i32 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.
void
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.
bool
compareAndSetAcqRel(self, expected : i32, update : i32) : bool 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.

Method detail

#get

get(self) : i32

Atomically read the current value.

#set

set(self, newValue : i32) : void

Atomically store newValue.

Parameters
newValue the i32 value to publish to all threads.

#incrementAndGet

incrementAndGet(self) : i32

Atomically add one.

Returns the value after the increment.

#decrementAndGet

decrementAndGet(self) : i32

Atomically subtract one.

Returns the value after the decrement.

#addAndGet

addAndGet(self, delta : i32) : i32

Atomically add delta.

Parameters
delta signed amount to add (negative to subtract).
Returns the value after the addition.

#compareAndSet

compareAndSet(self, expected : i32, update : i32) : bool

Atomically set the value to update only if it currently equals
expected (compare-and-swap).

Parameters
expected value the counter must currently hold for the swap to occur.
update value to store when the witnessed value matches expected.
Returns true if the swap happened, false if the witnessed value
differed from expected.

#swap

swap(self, newValue : i32) : i32

Atomically store newValue and return the value it replaced.

Parameters
newValue the i32 value to publish to all threads.
Returns the value held before the store.

#getAcquire

getAcquire(self) : i32

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

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.

Parameters
newValue the i32 value to publish.

#compareAndSetAcqRel

compareAndSetAcqRel(self, expected : i32, update : i32) : bool

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.

Parameters
expected value the counter must currently hold for the swap to occur.
update value to store when the witnessed value matches expected.
Returns 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

TypeMethod and description
constructor(initial : i64)

Method detail

#constructor

constructor(initial : i64)

Parameters
initial starting value of the counter.

Methods

TypeMethod and description
i64
get(self) : i64 Atomically read the current value.
void
set(self, newValue : i64) : void Atomically store newValue.
i64
incrementAndGet(self) : i64 Atomically add one.
i64
decrementAndGet(self) : i64 Atomically subtract one.
i64
addAndGet(self, delta : i64) : i64 Atomically add delta.
bool
compareAndSet(self, expected : i64, update : i64) : bool Atomically set the value to update only if it currently equals
expected (compare-and-swap).
i64
swap(self, newValue : i64) : i64 Atomically store newValue and return the value it replaced.
i64
getAcquire(self) : i64 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.
void
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.
bool
compareAndSetAcqRel(self, expected : i64, update : i64) : bool 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.

Method detail

#get

get(self) : i64

Atomically read the current value.

#set

set(self, newValue : i64) : void

Atomically store newValue.

Parameters
newValue the i64 value to publish to all threads.

#incrementAndGet

incrementAndGet(self) : i64

Atomically add one.

Returns the value after the increment.

#decrementAndGet

decrementAndGet(self) : i64

Atomically subtract one.

Returns the value after the decrement.

#addAndGet

addAndGet(self, delta : i64) : i64

Atomically add delta.

Parameters
delta signed amount to add (negative to subtract).
Returns the value after the addition.

#compareAndSet

compareAndSet(self, expected : i64, update : i64) : bool

Atomically set the value to update only if it currently equals
expected (compare-and-swap).

Parameters
expected value the counter must currently hold for the swap to occur.
update value to store when the witnessed value matches expected.
Returns true if the swap happened, false if the witnessed value
differed from expected.

#swap

swap(self, newValue : i64) : i64

Atomically store newValue and return the value it replaced.

Parameters
newValue the i64 value to publish to all threads.
Returns the value held before the store.

#getAcquire

getAcquire(self) : i64

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

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.

Parameters
newValue the i64 value to publish.

#compareAndSetAcqRel

compareAndSetAcqRel(self, expected : i64, update : i64) : bool

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.

Parameters
expected value the counter must currently hold for the swap to occur.
update value to store when the witnessed value matches expected.
Returns true if the swap happened.

C class AtomicBoolean

Boolean flag with atomic load / store / CAS. Backed by an
AtomicBool on the Rust side so a writer and a reader on
different threads observe a single-step transition.

Constructors

TypeMethod and description
constructor(initial : bool)

Method detail

#constructor

constructor(initial : bool)

Parameters
initial starting value of the flag.

Methods

TypeMethod and description
bool
get(self) : bool Atomically read the current value.
void
set(self, newValue : bool) : void Atomically store newValue.
bool
compareAndSet(self, expected : bool, update : bool) : bool Atomically set the value to update only if it currently equals
expected (compare-and-swap).
bool
getAcquire(self) : bool 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.
void
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.
bool
compareAndSetAcqRel(self, expected : bool, update : bool) : bool 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.

Method detail

#get

get(self) : bool

Atomically read the current value.

#set

set(self, newValue : bool) : void

Atomically store newValue.

Parameters
newValue the bool flag value to publish to all threads.

#compareAndSet

compareAndSet(self, expected : bool, update : bool) : bool

Atomically set the value to update only if it currently equals
expected (compare-and-swap).

Parameters
expected value the flag must currently hold for the swap to occur.
update value to store when the witnessed value matches expected.
Returns true if the swap happened, false if the witnessed value
differed from expected.

#getAcquire

getAcquire(self) : bool

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

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.

Parameters
newValue the bool flag value to publish.

#compareAndSetAcqRel

compareAndSetAcqRel(self, expected : bool, update : bool) : bool

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.

Parameters
expected value the flag must currently hold for the swap to occur.
update value to store when the witnessed value matches expected.
Returns 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

TypeMethod and description
constructor(count : i32) 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.

Method detail

#constructor

constructor(count : i32)

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.

Parameters
count number of countDown() calls before the latch opens

Methods

TypeMethod and description
void
countDown(self) : void Decrement the count by one; releases waiters once it reaches zero.
void
waitFor(self) : void Block until the count reaches zero. await is reserved by the
async/await sugar; the latch primitive uses waitFor (matches
Condition.waitFor).
bool
waitForWithTimeout(self, millis : i64) : bool Block until the count reaches zero or the deadline elapses.
i32
getCount(self) : i32 The current remaining count.

Method detail

#countDown

countDown(self) : void

Decrement the count by one; releases waiters once it reaches zero.

#waitFor

waitFor(self) : void ! InterruptedException

Block until the count reaches zero. await is reserved by the
async/await sugar; the latch primitive uses waitFor (matches
Condition.waitFor).

#waitForWithTimeout

waitForWithTimeout(self, millis : i64) : bool ! InterruptedException

Block until the count reaches zero or the deadline elapses.

Parameters
millis maximum time to wait, in milliseconds.
Returns true if the count reached zero, false if it timed out.

#getCount

getCount(self) : i32

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

TypeMethod and description
void
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.
void
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's
acquisition is never released in its place.
void
writeLock(self) : void Acquire the exclusive write lock, blocking until no reader or writer holds it.
void
writeUnlock(self) : void Release the exclusive write lock. Throws IllegalStateException when
the caller does not hold it.
bool
tryReadLock(self) : bool Try to acquire a shared read lock without blocking.
bool
tryWriteLock(self) : bool Try to acquire the exclusive write lock without blocking.

Method detail

#readLock

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

readUnlock(self) : void ! IllegalStateException

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's
acquisition is never released in its place.

#writeLock

writeLock(self) : void

Acquire the exclusive write lock, blocking until no reader or writer holds it.

#writeUnlock

writeUnlock(self) : void ! IllegalStateException

Release the exclusive write lock. Throws IllegalStateException when
the caller does not hold it.

#tryReadLock

tryReadLock(self) : bool

Try to acquire a shared read lock without blocking.

Returns true if acquired, false if a writer holds the lock or waits for it.

#tryWriteLock

tryWriteLock(self) : bool

Try to acquire the exclusive write lock without blocking.

Returns 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

TypeMethod and description
constructor(permits : i32)

Method detail

#constructor

constructor(permits : i32)

Parameters
permits initial number of permits in the pool.

Methods

TypeMethod and description
void
acquire(self) : void Take one permit, blocking until one becomes available.
bool
tryAcquire(self) : bool Try to take one permit without blocking.
void
release(self) : void Return one permit to the pool, potentially unblocking a waiter.
i32
availablePermits(self) : i32 The number of permits currently available (a snapshot).

Method detail

#acquire

acquire(self) : void ! InterruptedException

Take one permit, blocking until one becomes available.

#tryAcquire

tryAcquire(self) : bool

Try to take one permit without blocking.

Returns true if a permit was taken, false if none were available.

#release

release(self) : void

Return one permit to the pool, potentially unblocking a waiter.

#availablePermits

availablePermits(self) : i32

The number of permits currently available (a snapshot).

T trait Condition

Wait/notify primitive paired with a lock: a task parks in
waitFor until another signals the condition.

TypeMethod and description
void
waitFor(self) : void Atomically release the lock and block until signalled, then
re-acquire the lock before returning.
void
waitForMillis(self, millis : i64) : void Like waitFor, but also returns once the deadline elapses.
void
signal(self) : void Wake one task waiting on this condition.
void
signalAll(self) : void Wake all tasks waiting on this condition.

Method detail

#waitFor

waitFor(self) : void ! InterruptedException

Atomically release the lock and block until signalled, then
re-acquire the lock before returning.

#waitForMillis

waitForMillis(self, millis : i64) : void ! InterruptedException

Like waitFor, but also returns once the deadline elapses.

Parameters
millis maximum time to wait, in milliseconds.

#signal

signal(self) : void

Wake one task waiting on this condition.

#signalAll

signalAll(self) : void

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.

TypeMethod and description
void
send(self, value : i32) : void Enqueue a value, blocking if the channel is bounded and full.
i32
receive(self) : i32 Dequeue the next value, blocking until one is available.
bool
trySend(self, value : i32) : bool Non-blocking enqueue.
i32
tryReceive(self) : i32 Non-blocking dequeue; returns immediately whether or not a value
is ready.
void
close(self) : void Close the channel; subsequent sends fail and pending receives drain.

Method detail

#send

send(self, value : i32) : void ! InterruptedException

Enqueue a value, blocking if the channel is bounded and full.

#receive

receive(self) : i32 ! InterruptedException

Dequeue the next value, blocking until one is available.

#trySend

trySend(self, value : i32) : bool

Non-blocking enqueue.

Returns true if the value was accepted, false if the channel
is full or closed.

#tryReceive

tryReceive(self) : i32

Non-blocking dequeue; returns immediately whether or not a value
is ready.

#close

close(self) : void ! IOException

Close the channel; subsequent sends fail and pending receives drain.