hakojs
Version:
A secure, embeddable JavaScript engine that runs untrusted code inside WebAssembly sandboxes with fine-grained permissions and resource limits
192 lines • 7.35 kB
TypeScript
/**
* memory.ts - Memory management utilities for PrimJS wrapper
*
* This module provides a MemoryManager class that handles WebAssembly memory operations
* for the PrimJS runtime. It includes functions for allocating, reading, writing, and
* freeing memory in the WebAssembly heap, with special handling for JavaScript values,
* strings, and arrays of pointers.
*/
import type { HakoExports } from "../etc/ffi";
import type { CString, JSContextPointer, JSRuntimePointer, JSValuePointer } from "../etc/types";
/**
* Handles memory operations for the PrimJS WebAssembly module.
*
* MemoryManager provides an abstraction layer over the raw WebAssembly memory
* operations, handling allocation, deallocation, and data transfer between
* JavaScript and the WebAssembly environment. It includes utilities for working
* with strings, pointers, arrays, and JavaScript values in WebAssembly memory.
*/
export declare class MemoryManager {
/**
* Reference to the WebAssembly exports object, which contains
* memory management functions and the memory buffer.
* @private
*/
private exports;
/**
* TextEncoder instance for converting JavaScript strings to UTF-8 byte arrays.
* @private
*/
private encoder;
/**
* TextDecoder instance for converting UTF-8 byte arrays to JavaScript strings.
* @private
*/
private decoder;
/**
* Sets the WebAssembly exports object after module instantiation.
* This must be called before any other MemoryManager methods.
*
* @param exports - The PrimJS WebAssembly exports object
*/
setExports(exports: HakoExports): void;
/**
* Checks if the exports object has been set and returns it.
*
* @returns The PrimJS WebAssembly exports object
* @throws Error if exports are not set
* @private
*/
private checkExports;
/**
* Allocates a block of memory in the WebAssembly heap.
*
* @param size - Size of memory block to allocate in bytes
* @returns Pointer to the allocated memory
* @throws Error if memory allocation fails
*/
allocateMemory(ctx: JSContextPointer, size: number): number;
allocateRuntimeMemory(rt: JSRuntimePointer, size: number): number;
/**
* Frees a block of memory in the WebAssembly heap.
*
* @param ptr - Pointer to the memory block to free
*/
freeMemory(ctx: JSContextPointer, ptr: number): void;
freeRuntimeMemory(rt: JSRuntimePointer, ptr: number): void;
/**
* Writes a Uint8Array to WebAssembly memory.
* @param bytes - Uint8Array to write to WebAssembly memory
* @returns Pointer to the allocated memory
*/
writeBytes(ctx: JSContextPointer, bytes: Uint8Array): number;
/**
* Creates a null-terminated C string in the WebAssembly heap.
*
* Encodes the JavaScript string to UTF-8, allocates memory for it,
* and copies the bytes to WebAssembly memory with a null terminator.
*
* @param str - JavaScript string to convert to a C string
* @returns Pointer to the C string in WebAssembly memory
*/
allocateString(ctx: JSContextPointer, str: string): CString;
copy(offset: number, length: number): Uint8Array;
slice(offset: number, length: number): Uint8Array;
writeNullTerminatedString(ctx: JSContextPointer, str: string): {
pointer: CString;
length: number;
};
/**
* Reads a null-terminated C string from the WebAssembly heap.
*
* @param ptr - Pointer to the C string
* @returns JavaScript string
*/
readString(ptr: CString): string;
/**
* Frees a C string created by PrimJS.
*
* This uses the PrimJS-specific function to free strings that were
* allocated by the PrimJS engine, rather than by us.
*
* @param ctx - PrimJS context pointer
* @param ptr - Pointer to the C string
*/
freeCString(ctx: JSContextPointer, ptr: CString): void;
/**
* Frees a JavaScript value pointer in a specific context.
*
* @param ctx - PrimJS context pointer
* @param ptr - Pointer to the JavaScript value
*/
freeValuePointer(ctx: JSContextPointer, ptr: JSValuePointer): void;
/**
* Frees a JavaScript value pointer using the runtime instead of a context.
*
* This is useful for freeing values when a context is not available,
* but should be used carefully as it bypasses some safety checks.
*
* @param rt - PrimJS runtime pointer
* @param ptr - Pointer to the JavaScript value
*/
freeValuePointerRuntime(rt: JSRuntimePointer, ptr: JSValuePointer): void;
/**
* Duplicates a JavaScript value pointer.
*
* This creates a new reference to the same JavaScript value,
* incrementing its reference count in the PrimJS engine.
*
* @param ctx - PrimJS context pointer
* @param ptr - Pointer to the JavaScript value
* @returns Pointer to the duplicated JavaScript value
*/
dupValuePointer(ctx: JSContextPointer, ptr: JSValuePointer): JSValuePointer;
/**
* Creates a new ArrayBuffer JavaScript value.
*
* Allocates memory for the provided data and creates an ArrayBuffer
* that references this memory in the WebAssembly environment.
*
* @param ctx - PrimJS context pointer
* @param data - The data to store in the ArrayBuffer
* @returns Pointer to the new JavaScript ArrayBuffer value
*/
newArrayBuffer(ctx: JSContextPointer, data: Uint8Array): JSValuePointer;
/**
* Allocates memory for an array of pointers.
*
* @param count - Number of pointers to allocate space for
* @returns Pointer to the array in WebAssembly memory
*/
allocatePointerArray(ctx: JSContextPointer, count: number): number;
allocateRuntimePointerArray(rt: JSRuntimePointer, count: number): number;
/**
* Writes a pointer value to an array of pointers.
*
* @param arrayPtr - Pointer to the array
* @param index - Index in the array to write to
* @param value - Pointer value to write
* @returns The memory address that was written to
*/
writePointerToArray(arrayPtr: number, index: number, value: number): number;
/**
* Reads a pointer value from an array of pointers.
*
* @param arrayPtr - Pointer to the array
* @param index - Index in the array to read from
* @returns The pointer value at the specified index
*/
readPointerFromArray(arrayPtr: number, index: number): number;
/**
* Reads a pointer value from a specific memory address.
*
* @param address - Memory address to read from
* @returns The pointer value at the specified address
*/
readPointer(address: number): number;
/**
* Reads a 32-bit unsigned integer from a specific memory address.
*
* @param address - Memory address to read from
* @returns The uint32 value at the specified address
*/
readUint32(address: number): number;
/**
* Writes a 32-bit unsigned integer to a specific memory address.
*
* @param address - Memory address to write to
* @param value - Uint32 value to write
*/
writeUint32(address: number, value: number): void;
}
//# sourceMappingURL=memory.d.ts.map