Async API Reference

High-level async utilities: timeout, retry, race, async channels

Import

U std/async

Types

TimeoutFuture

Wraps a future with a deadline. Returns -1 if not completed in time.

RetryConfig

Configurable retry logic with exponential backoff.

MethodSignatureDescription
newF new(max_retries: i64) -> RetryConfigCreate with default backoff
with_backoffF with_backoff(max: i64, base: i64, factor: i64) -> RetryConfigCustom backoff
should_retryF should_retry(&self) -> i64Check if retries remain
record_retryF record_retry(&self) -> i64Record attempt, returns delay
retriesF retries(&self) -> i64Get current retry count
remainingF remaining(&self) -> i64Get remaining retries

RaceFuture

Races multiple futures and returns the first completed result.

S RaceFuture { futures: i64, count: i64, completed: i64 }
MethodSignatureDescription
newF new(count: i64) -> RaceFutureCreate with capacity for N futures
addF add(&self, index: i64, future_ptr: i64, poll_fn: i64) -> i64Add future to race
winnerF winner(&self) -> i64Get index of completed future
cleanupF cleanup(&self) -> i64Free memory

AsyncMutex

Async-aware mutual exclusion (non-blocking try_lock).

S AsyncMutex { locked: i64, value: i64, waiters: i64, waiter_head: i64 }
MethodSignatureDescription
newF new(value: i64) -> AsyncMutexCreate with protected value
try_lockF try_lock(&self) -> i64Try to acquire (returns 1 if acquired)
unlockF unlock(&self) -> i64Release the lock
getF get(&self) -> i64Get protected value (must be locked)
setF set(&self, value: i64) -> i64Set protected value (must be locked)
is_lockedF is_locked(&self) -> i64Check if locked

AsyncChannel

Async-aware bounded channel with non-blocking send/receive.

S AsyncChannel { buffer: i64, capacity: i64, head: i64, tail: i64, len: i64, closed: i64 }
MethodSignatureDescription
newF new(capacity: i64) -> AsyncChannelCreate channel
try_sendF try_send(&self, value: i64) -> i64Non-blocking send (0=ok, 1=full, 2=closed)
try_recvF try_recv(&self) -> i64Non-blocking receive (value or -1=empty, -2=closed)
closeF close(&self) -> i64Close channel
is_emptyF is_empty(&self) -> i64Check if empty
is_fullF is_full(&self) -> i64Check if full
pendingF pending(&self) -> i64Count pending messages
is_closedF is_closed(&self) -> i64Check if closed
cleanupF cleanup(&self) -> i64Free buffer memory

Debounce

Delays execution until input settles.

S Debounce { delay: i64, last_trigger: i64, pending: i64 }
MethodSignatureDescription
newF new(delay: i64) -> DebounceCreate with delay in ticks
triggerF trigger(&self, current_tick: i64) -> i64Trigger (resets timer)
should_executeF should_execute(&self, current_tick: i64) -> i64Check if should execute

Throttle

Limits execution rate.

S Throttle { interval: i64, last_exec: i64 }
MethodSignatureDescription
newF new(interval: i64) -> ThrottleCreate with minimum interval
try_executeF try_execute(&self, current_tick: i64) -> i64Check if allowed (returns 1 if executed)

Helper Functions

FunctionSignatureDescription
timeoutF timeout(inner_ptr, inner_poll, deadline) -> TimeoutFutureWrap with timeout
with_timeoutF with_timeout(inner_ptr, inner_poll, deadline) -> TimeoutFutureCreate a timeout (alias)
retryF retry(max_retries: i64) -> RetryConfigCreate retry config
async_mutexF async_mutex(value: i64) -> AsyncMutexCreate async mutex
async_channelF async_channel(capacity: i64) -> AsyncChannelCreate async channel

Usage

U std/async

F main() -> i64 {
    # AsyncChannel example
    ch := async_channel(32)
    ch.try_send(42)
    val := ch.try_recv()  # 42
    ch.close()

    # AsyncMutex example
    mtx := async_mutex(100)
    mtx.try_lock()
    val := mtx.get()  # 100
    mtx.set(200)
    mtx.unlock()

    # RetryConfig example
    cfg := retry(3)
    cfg.retries()  # 0
    cfg.remaining()  # 3

    # Debounce example
    db := Debounce::new(10)
    db.trigger(0)
    db.should_execute(15)  # 1

    # Throttle example
    th := Throttle::new(5)
    th.try_execute(0)  # 1
    th.try_execute(3)  # 0 (too soon)

    0
}