lib: allocator interface based on Zig allocators

include/ghostty-vt.h

@@ -7,6 +7,127 @@
 extern "C" {
 #endif
 
+#include <stddef.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+//-------------------------------------------------------------------
+// Types
+
+typedef struct GhosttyOscParser GhosttyOscParser;
+
+typedef enum {
+    GHOSTTY_VT_SUCCESS = 0,
+    GHOSTTY_VT_OUT_OF_MEMORY = -1,
+} GhosttyVtResult;
+
+typedef struct {
+    /**
+     * Return a pointer to `len` bytes with specified `alignment`, or return
+     * `NULL` indicating the allocation failed.
+     *
+     * @param ctx The allocator context
+     * @param len Number of bytes to allocate
+     * @param alignment Required alignment for the allocation. Guaranteed to
+     *   be a power of two between 1 and 16 inclusive.
+     * @param ret_addr First return address of the allocation call stack (0 if not provided)
+     * @return Pointer to allocated memory, or NULL if allocation failed
+     */
+    void* (*alloc)(void *ctx, size_t len, uint8_t alignment, uintptr_t ret_addr);
+    
+    /**
+     * Attempt to expand or shrink memory in place.
+     *
+     * `memory_len` must equal the length requested from the most recent
+     * successful call to `alloc`, `resize`, or `remap`. `alignment` must
+     * equal the same value that was passed as the `alignment` parameter to
+     * the original `alloc` call.
+     *
+     * `new_len` must be greater than zero.
+     *
+     * @param ctx The allocator context
+     * @param memory Pointer to the memory block to resize
+     * @param memory_len Current size of the memory block
+     * @param alignment Alignment (must match original allocation)
+     * @param new_len New requested size
+     * @param ret_addr First return address of the allocation call stack (0 if not provided)
+     * @return true if resize was successful in-place, false if relocation would be required
+     */
+    bool (*resize)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr);
+    
+    /**
+     * Attempt to expand or shrink memory, allowing relocation.
+     *
+     * `memory_len` must equal the length requested from the most recent
+     * successful call to `alloc`, `resize`, or `remap`. `alignment` must
+     * equal the same value that was passed as the `alignment` parameter to
+     * the original `alloc` call.
+     *
+     * A non-`NULL` return value indicates the resize was successful. The
+     * allocation may have same address, or may have been relocated. In either
+     * case, the allocation now has size of `new_len`. A `NULL` return value
+     * indicates that the resize would be equivalent to allocating new memory,
+     * copying the bytes from the old memory, and then freeing the old memory.
+     * In such case, it is more efficient for the caller to perform the copy.
+     *
+     * `new_len` must be greater than zero.
+     *
+     * @param ctx The allocator context
+     * @param memory Pointer to the memory block to remap
+     * @param memory_len Current size of the memory block
+     * @param alignment Alignment (must match original allocation)
+     * @param new_len New requested size
+     * @param ret_addr First return address of the allocation call stack (0 if not provided)
+     * @return Pointer to resized memory (may be relocated), or NULL if manual copy is needed
+     */
+    void* (*remap)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr);
+    
+    /**
+     * Free and invalidate a region of memory.
+     *
+     * `memory_len` must equal the length requested from the most recent
+     * successful call to `alloc`, `resize`, or `remap`. `alignment` must
+     * equal the same value that was passed as the `alignment` parameter to
+     * the original `alloc` call.
+     *
+     * @param ctx The allocator context
+     * @param memory Pointer to the memory block to free
+     * @param memory_len Size of the memory block
+     * @param alignment Alignment (must match original allocation)
+     * @param ret_addr First return address of the allocation call stack (0 if not provided)
+     */
+    void (*free)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, uintptr_t ret_addr);
+} GhosttyVtAllocatorVtable;
+
+/**
+ * Custom memory allocator.
+ *
+ * Usage example:
+ * @code
+ * GhosttyVtAllocator allocator = {
+ *     .vtable = &my_allocator_vtable,
+ *     .ctx = my_allocator_state
+ * };
+ * @endcode
+ */
+typedef struct {
+    /**
+     * Opaque context pointer passed to all vtable functions.
+     * This allows the allocator implementation to maintain state
+     * or reference external resources needed for memory management.
+     */
+    void *ctx;
+
+    /**
+     * Pointer to the allocator's vtable containing function pointers
+     * for memory operations (alloc, resize, remap, free).
+     */
+    const GhosttyVtAllocatorVtable *vtable;
+} GhosttyVtAllocator;
+
+//-------------------------------------------------------------------
+// Functions
+
 #ifdef __cplusplus
 }
 #endif