Future API Reference

Stackless coroutine-based async/await with future combinators

Import

U std/future

Core Types

Poll

E Poll {
    Pending,
    Ready(i64)
}

Result type for polling futures.

Future (trait)

W Future {
    F poll(&self, ctx: i64) -> Poll
}

Trait for asynchronous values. Types implementing this can be polled for completion.

Context

S Context {
    waker_ptr: i64,
    runtime_ptr: i64
}

Context passed to poll operations, contains waker and runtime information.

Waker

S Waker {
    task_ptr: i64,
    wake_fn: i64
}

Mechanism to wake up a suspended task.

Future Combinators

MapFuture

S MapFuture {
    inner_ptr: i64,     # Pointer to inner future
    inner_poll: i64,    # Poll function of inner future
    map_fn: i64,        # Mapping function pointer
    state: i64          # 0 = not polled, 1 = complete
}

Transforms the output of a future using a mapping function.

AndThenFuture

S AndThenFuture {
    first_ptr: i64,     # First future
    first_poll: i64,
    second_fn: i64,     # Function that creates second future from first result
    state: i64,         # 0 = running first, 1 = running second
    second_ptr: i64,    # Created second future (when state = 1)
    second_poll: i64
}

Chains futures sequentially - runs second future after first completes.

JoinFuture

S JoinFuture {
    first_ptr: i64,
    first_poll: i64,
    second_ptr: i64,
    second_poll: i64,
    first_done: i64,
    second_done: i64,
    first_result: i64,
    second_result: i64
}

Runs two futures concurrently, completes when both finish.

SelectFuture

S SelectFuture {
    first_ptr: i64,
    first_poll: i64,
    second_ptr: i64,
    second_poll: i64
}

Returns when either future completes (race condition).

ReadyFuture

S ReadyFuture {
    value: i64
}

Future that immediately resolves to a value.

PendingFuture

S PendingFuture {
    _dummy: i64
}

Future that never resolves (always returns Pending).

TimerFuture

S TimerFuture {
    deadline: i64,      # Target tick count
    started: i64
}

Future that completes after N iterations.

YieldNow

S YieldNow {
    yielded: i64
}

Cooperative scheduling yield point. Returns Pending on first poll, Ready on second.

AsyncDrop Support

AsyncDrop (trait)

W AsyncDrop {
    A F async_drop(&self) -> i64
}

Trait for types that need async cleanup when they go out of scope.

AsyncDropGuard

S AsyncDropGuard {
    value_ptr: i64,         # Pointer to the value
    drop_fn: i64,           # Async drop function pointer (poll-based)
    dropped: i64            # 1 if already dropped
}

Wraps a value implementing AsyncDrop and ensures async_drop is called.

AsyncDropScope

S AsyncDropScope {
    head: i64,          # First guard in linked list
    count: i64          # Number of guards
}

Manages multiple AsyncDrop resources. All resources are dropped in reverse order (LIFO) when scope ends.

Helper Functions

Usage

Basic Future

U std/future

F main() -> i64 {
    # Create immediately-ready future
    f := ready(42)

    # In async context: poll the future
    ctx := Context::new()
    result := f.poll(ctx)

    I result.is_ready() {
        value := result.unwrap()  # value = 42
    }
    0
}

Join Futures

U std/future

F main() -> i64 {
    f1 := ready(10)
    f2 := ready(20)

    # Join both futures
    joined := join(f1_ptr, f1_poll, f2_ptr, f2_poll)

    # Poll until both complete
    0
}

Async Drop

U std/future

# Example: Connection with async cleanup
S MyConn {
    handle: i64
}

X MyConn: AsyncDrop {
    A F async_drop(&self) -> i64 {
        # Close connection asynchronously
        close_connection(self.handle)
    }
}

F main() -> i64 {
    scope := async_drop_scope()

    # Register resource for async cleanup
    conn := MyConn { handle: open_connection() }
    guard := scope.register(conn_ptr, drop_fn)

    # Do work...

    # All resources cleaned up in reverse order
    scope.drop_all()
    0
}