#Module async

Promises, microtasks, buffers and host objects: the asynchronous core every other module builds on.

A promise's value is an i64 (a number, or the handle of a buffer or another object) plus a string (an error message, a text result). Reactions run as microtasks once it settles. There are no closures in Wasm, so then does not create a chained promise: a reaction that passes a result on resolves a promise of its own.

A buffer is the ArrayBuffer of this platform: bytes owned by the browser, passed between APIs without copies into the module's memory (fetch bodies, messages, socket frames), counted against page.max_fetch_bytes.

Exposed to: Window, Worker. Source: api/async.widl.

Odin: import "wren:core".

#Types

#handle Object : EventTarget

Any host object (not a node). Released with Object_release; freed with the page in any case.

Checked by the browser on every call (lookup_Object).

#handle Promise : Object

Checked by the browser on every call (lookup_Promise).

#handle Buffer : Object

An ArrayBuffer.

Checked by the browser on every call (lookup_Buffer).

#enum PromiseState : i32

#callback MicrotaskCallback

void MicrotaskCallback(i32 user)

#callback PromiseReaction

void PromiseReaction(i32 user, Promise promise, PromiseState state)

A reaction: read the result with Promise_value / Promise_text.

#Functions

#queueMicrotask

void queueMicrotask(MicrotaskCallback callback, i32 user = 0)

queueMicrotask(callback)

Host: queueMicrotask :: proc(c: ^Call, callback: u32, user: i32)

#Promise_create

Promise Promise_create()

A pending promise the module settles itself.

Host: Promise_create :: proc(c: ^Call) -> u64

#Promise_resolve

void Promise_resolve(Promise promise, i64 value = 0, string text = "") raises

Fulfils a pending promise. Invalid_Argument when it is settled already.

Raises: returns an Error (see web).

Host: Promise_resolve :: proc(c: ^Call, promise: Api_Promise, value: i64, text: string) -> Api_Error

#Promise_reject

void Promise_reject(Promise promise, i64 code, string message = "") raises

Rejects a pending promise with an Error code (or any value) and a message. Invalid_Argument when settled already.

Raises: returns an Error (see web).

Host: Promise_reject :: proc(c: ^Call, promise: Api_Promise, code: i64, message: string) -> Api_Error

#Promise_then

void Promise_then(Promise promise, PromiseReaction callback, i32 user = 0)

Adds a reaction; queued at once when the promise is settled already.

Host: Promise_then :: proc(c: ^Call, promise: Api_Promise, callback: u32, user: i32)

#Promise_state

PromiseState Promise_state(Promise promise)

Host: Promise_state :: proc(c: ^Call, promise: Api_Promise) -> Api_PromiseState

#Promise_value

i64 Promise_value(Promise promise)

The value (fulfilled) or the code (rejected).

Host: Promise_value :: proc(c: ^Call, promise: Api_Promise) -> i64

#Promise_text

string Promise_text(Promise promise)

The text result (fulfilled) or the message (rejected).

Host: Promise_text :: proc(c: ^Call, promise: Api_Promise) -> string

#Promise_all

Promise Promise_all(Promise[] promises)

Promise.all: fulfilled (value = the count) when every one is, rejected with the first rejection's value and text.

Host: Promise_all :: proc(c: ^Call, promises: []u64) -> u64

#Object_release

void Object_release(Object object) raises

Releases a host object of any kind.

Raises: returns an Error (see web).

Host: Object_release :: proc(c: ^Call, object: Api_Object) -> Api_Error

#Object_kind

string Object_kind(Object object)

The interface name of an object ("Promise", "ArrayBuffer"...).

Host: Object_kind :: proc(c: ^Call, object: Api_Object) -> string

#Buffer_create

Buffer Buffer_create(bytes data) raises

A buffer holding a copy of data. Quota past the page's memory limit.

Raises: returns an Error (see web).

Host: Buffer_create :: proc(c: ^Call, data: []u8) -> (u64, Api_Error)

#Buffer_alloc

Buffer Buffer_alloc(i64 length) raises

A zero-filled buffer of length bytes. Quota past the page's memory limit, Range for a negative length.

Raises: returns an Error (see web).

Host: Buffer_alloc :: proc(c: ^Call, length: i64) -> (u64, Api_Error)

#Buffer_length

i64 Buffer_length(Buffer buffer)

byteLength (0 once detached by a transfer).

Host: Buffer_length :: proc(c: ^Call, buffer: Api_Buffer) -> i64

#Buffer_read

i32 Buffer_read(Buffer buffer, i64 offset, out bytes destination)

Copies bytes from offset into destination; returns how many.

Host: Buffer_read :: proc(c: ^Call, buffer: Api_Buffer, offset: i64, destination: []u8) -> i32

#Buffer_write

i32 Buffer_write(Buffer buffer, i64 offset, bytes source)

Copies source into the buffer at offset (what fits); returns how many bytes were written.

Host: Buffer_write :: proc(c: ^Call, buffer: Api_Buffer, offset: i64, source: []u8) -> i32

#Buffer_slice

Buffer Buffer_slice(Buffer buffer, i64 start, i64 end) raises

buffer.slice(start, end): a copy; negative positions count from the end. Quota past the page's memory limit.

Raises: returns an Error (see web).

Host: Buffer_slice :: proc(c: ^Call, buffer: Api_Buffer, start: i64, end: i64) -> (u64, Api_Error)

Edit this page on GitHub