diff options
| author | Can Celik <ogulcancelik@gmail.com> | 2026-09-10 21:51:57 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-09-10 21:51:57 +0300 |
| commit | 425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch) | |
| tree | e52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/include/ghostty/vt/wasm.h | |
| parent | 90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff) | |
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/include/ghostty/vt/wasm.h')
| -rw-r--r-- | vendor/libghostty-vt/include/ghostty/vt/wasm.h | 168 |
1 files changed, 84 insertions, 84 deletions
diff --git a/vendor/libghostty-vt/include/ghostty/vt/wasm.h b/vendor/libghostty-vt/include/ghostty/vt/wasm.h index e2b63e2c..2f9ff5df 100644 --- a/vendor/libghostty-vt/include/ghostty/vt/wasm.h +++ b/vendor/libghostty-vt/include/ghostty/vt/wasm.h @@ -10,12 +10,12 @@ #ifdef __wasm__ #include <stddef.h> -#include <stdint.h> #include <ghostty/vt/types.h> /** @defgroup wasm WebAssembly Utilities * - * Convenience functions for allocating various types in WebAssembly builds. + * Convenience functions for working with the low-level C ABI in WebAssembly + * builds. * **These are only available the libghostty-vt wasm module.** * * Ghostty relies on pointers to various types for ABI compatibility, and @@ -28,37 +28,64 @@ * your custom allocator. This is a very rare use case in the WebAssembly * world so these are optimized for simplicity. * + * Use ghostty_wasm_alloc() and ghostty_wasm_free() for host-owned scratch + * buffers and ABI values. 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. 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. + * + * ## Memory growth + * + * 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. + * * ## Example Usage * - * Here's a simple example of using the Wasm utilities with the key encoder: + * Here's a simple example that creates a terminal, writes bytes, and safely + * handles memory growth: * * @code * const { exports } = wasmInstance; - * const view = new DataView(wasmMemory.buffer); - * - * // Create key encoder - * const encoderPtr = exports.ghostty_wasm_alloc_opaque(); - * exports.ghostty_key_encoder_new(null, encoderPtr); - * const encoder = view.getUint32(encoder, true); - * - * // Configure encoder with Kitty protocol flags - * const flagsPtr = exports.ghostty_wasm_alloc_u8(); - * view.setUint8(flagsPtr, 0x1F); - * exports.ghostty_key_encoder_setopt(encoder, 5, flagsPtr); - * - * // Allocate output buffer and size pointer - * const bufferSize = 32; - * const bufPtr = exports.ghostty_wasm_alloc_u8_array(bufferSize); - * const writtenPtr = exports.ghostty_wasm_alloc_usize(); - * - * // Encode the key event - * exports.ghostty_key_encoder_encode( - * encoder, eventPtr, bufPtr, bufferSize, writtenPtr - * ); - * - * // Read encoded output - * const bytesWritten = view.getUint32(writtenPtr, true); - * const encoded = new Uint8Array(wasmMemory.buffer, bufPtr, bytesWritten); + * 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); * @endcode * * @remark The code above is pretty ugly! This is the lowest level interface @@ -69,89 +96,62 @@ */ /** - * Allocate an opaque pointer. This can be used for any opaque pointer - * types such as GhosttyKeyEncoder, GhosttyKeyEvent, etc. - * - * @return Pointer to allocated opaque pointer, or NULL if allocation failed - * @ingroup wasm - */ -GHOSTTY_API void** ghostty_wasm_alloc_opaque(void); - -/** - * Free an opaque pointer allocated by ghostty_wasm_alloc_opaque(). - * - * @param ptr Pointer to free, or NULL (NULL is safely ignored) - * @ingroup wasm - */ -GHOSTTY_API void ghostty_wasm_free_opaque(void **ptr); - -/** - * Allocate an array of uint8_t values. + * Allocate caller-owned storage for a Wasm ABI value or scratch buffer. * - * @param len Number of uint8_t elements to allocate - * @return Pointer to allocated array, or NULL if allocation failed - * @ingroup wasm - */ -GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8_array(size_t len); - -/** - * Free an array allocated by ghostty_wasm_alloc_u8_array(). + * 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. * - * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored) - * @param len Length of the array (must match the length passed to alloc) - * @ingroup wasm - */ -GHOSTTY_API void ghostty_wasm_free_u8_array(uint8_t *ptr, size_t len); - -/** - * Allocate an array of uint16_t values. + * The returned pointer must be released with ghostty_wasm_free() using the + * exact same length. * - * @param len Number of uint16_t elements to allocate - * @return Pointer to allocated array, or NULL if allocation failed + * @param len Number of bytes to allocate + * @return Pointer to allocated storage, or NULL if len is zero or allocation + * failed * @ingroup wasm */ -GHOSTTY_API uint16_t* ghostty_wasm_alloc_u16_array(size_t len); +GHOSTTY_API void* ghostty_wasm_alloc(size_t len); /** - * Free an array allocated by ghostty_wasm_alloc_u16_array(). + * Free storage allocated by ghostty_wasm_alloc(). * - * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored) - * @param len Length of the array (must match the length passed to alloc) + * @param ptr Pointer to free, or NULL (NULL is safely ignored) + * @param len Original allocation length passed to ghostty_wasm_alloc() * @ingroup wasm */ -GHOSTTY_API void ghostty_wasm_free_u16_array(uint16_t *ptr, size_t len); +GHOSTTY_API void ghostty_wasm_free(void *ptr, size_t len); /** - * Allocate a single uint8_t value. + * 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. * - * @return Pointer to allocated uint8_t, or NULL if allocation failed + * @return Pointer to allocated opaque pointer, or NULL if allocation failed * @ingroup wasm */ -GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8(void); +GHOSTTY_API void** ghostty_wasm_alloc_opaque(void); /** - * Free a uint8_t allocated by ghostty_wasm_alloc_u8(). + * Free an opaque pointer allocated by ghostty_wasm_alloc_opaque(). * * @param ptr Pointer to free, or NULL (NULL is safely ignored) * @ingroup wasm */ -GHOSTTY_API void ghostty_wasm_free_u8(uint8_t *ptr); +GHOSTTY_API void ghostty_wasm_free_opaque(void **ptr); /** - * Allocate a single size_t value. + * Take an opaque handle from an out-parameter slot. * - * @return Pointer to allocated size_t, or NULL if allocation failed - * @ingroup wasm - */ -GHOSTTY_API size_t* ghostty_wasm_alloc_usize(void); - -/** - * Free a size_t allocated by ghostty_wasm_alloc_usize(). + * Returns the handle currently stored in @p 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. * - * @param ptr Pointer to free, or NULL (NULL is safely ignored) + * @param slot Pointer to an opaque out-parameter slot, or NULL + * @return Stored opaque handle, or NULL if slot or its value is NULL * @ingroup wasm */ -GHOSTTY_API void ghostty_wasm_free_usize(size_t *ptr); +GHOSTTY_API void* ghostty_wasm_take_opaque(void **slot); /** @} */ |
