WebAssembly

Allocate memory and pass pointers from a WebAssembly host. More...

Detailed Description

Allocate memory and pass pointers from a WebAssembly host.

These are helpers for calling the C API from WebAssembly, and they only exist in the wasm module.

The C API passes a lot of pointers, and creating those in Wasm can be tedious. Use ghostty_wasm_alloc() and ghostty_wasm_free() for buffers and ABI values, and the _opaque functions for handles. They only add to the C API. They don't change it.

Example

This creates a terminal, writes bytes, and safely handles memory growth. It's the lowest level interface to the module and it's pretty ugly. In practice, you should wrap it in a higher-level API.

const { exports } = wasmInstance;
const memory = exports.memory;
let cachedBuffer = null;
let cachedLength = 0;
let cachedBytes = null;
 
function bytes() {
  const buffer = memory.buffer;
  if (buffer !== cachedBuffer || buffer.byteLength !== cachedLength) {
    cachedBuffer = buffer;
    cachedLength = buffer.byteLength;
    cachedBytes = new Uint8Array(buffer);
  }
  return cachedBytes;
}
 
function check(result) {
  if (result !== 0) throw new Error(`libghostty-vt error: ${result}`);
}
 
// One slot can be reused for every opaque-handle constructor.
const slot = exports.ghostty_wasm_alloc_opaque();
if (slot === 0) throw new Error("out of memory");
check(exports.ghostty_terminal_new(0, slot, 80, 24));
const terminal = exports.ghostty_wasm_take_opaque(slot);
 
const input = new TextEncoder().encode("Hello, world!");
const inputPtr = exports.ghostty_wasm_alloc(input.length);
if (inputPtr === 0) throw new Error("out of memory");
bytes().set(input, inputPtr); // Acquires the current memory after alloc.
exports.ghostty_terminal_vt_write(terminal, inputPtr, input.length);
 
exports.ghostty_wasm_free(inputPtr, input.length);
exports.ghostty_terminal_free(terminal);
exports.ghostty_wasm_free_opaque(slot);

See wasm-vt for a full program, and WebAssembly for how to build the module.

Functions
GHOSTTY_API void *	ghostty_wasm_alloc (size_t len)
GHOSTTY_API void	ghostty_wasm_free (void *ptr, size_t len)
GHOSTTY_API void **	ghostty_wasm_alloc_opaque (void)
GHOSTTY_API void	ghostty_wasm_free_opaque (void **ptr)
GHOSTTY_API void *	ghostty_wasm_take_opaque (void **slot)

Function Documentation

ghostty_wasm_alloc()

GHOSTTY_API void * ghostty_wasm_alloc

(

size_t

len

)

Allocate caller-owned storage for a Wasm ABI value or scratch buffer.

The returned address is aligned to the target's maximum C ABI alignment, reported as abi.max_alignment by ghostty_type_json(). The memory is uninitialized. A zero-length request returns NULL.

The returned pointer must be released with ghostty_wasm_free() using the exact same length. Do not mix allocation families: buffers returned by libghostty-vt allocating APIs must still be released with ghostty_free(), and opaque handles must be released with their type-specific destructor.

This always uses the default allocator. If you need a custom allocation strategy, allocate types manually with your own allocator. That's very rare in WebAssembly, so these are optimized for simplicity.

Dynamic-language hosts can use ghostty_type_json() to discover pointer and size_t widths, maximum alignment, byte order, and the size and alignment of public C structs.

An exported function may grow Wasm linear memory when it allocates. Numeric pointers and handles remain valid, but JavaScript ArrayBuffer, DataView, and typed-array objects created before the growth may no longer cover the live memory. Reacquire exports.memory.buffer immediately before every host-side memory access. A host that caches views should recreate them whenever either the buffer identity or its byte length changes.

Parameters

len	Number of bytes to allocate

Returns

Pointer to allocated storage, or NULL if len is zero or allocation failed

ghostty_wasm_alloc_opaque()

GHOSTTY_API void ** ghostty_wasm_alloc_opaque

(

void

)

Allocate an opaque pointer. This can be used for any opaque pointer types such as GhosttyKeyEncoder, GhosttyKeyEvent, etc. The allocated slot is initialized to NULL and may be reused across constructors.

Returns

Pointer to allocated opaque pointer, or NULL if allocation failed

ghostty_wasm_free()

GHOSTTY_API void ghostty_wasm_free	(	void *	ptr,
		size_t	len )

Free storage allocated by ghostty_wasm_alloc().

Parameters

ptr	Pointer to free, or NULL (NULL is safely ignored)
len	Original allocation length passed to ghostty_wasm_alloc()

ghostty_wasm_free_opaque()

GHOSTTY_API void ghostty_wasm_free_opaque

(

void **

ptr

)

Free an opaque pointer allocated by ghostty_wasm_alloc_opaque().

Parameters

ptr	Pointer to free, or NULL (NULL is safely ignored)

ghostty_wasm_take_opaque()

GHOSTTY_API void * ghostty_wasm_take_opaque

(

void **

slot

)

Take an opaque handle from an out-parameter slot.

Returns the handle currently stored in slot and resets the slot to NULL. This function does not allocate, free the returned handle, or free the slot. Always check the GhosttyResult returned by the function that populated the slot before calling this function.

Parameters

slot	Pointer to an opaque out-parameter slot, or NULL

Returns

Stored opaque handle, or NULL if slot or its value is NULL