GhosttyAllocatorVtable Struct Reference

#include <ghostty/vt/allocator.h>

Data Fields
void *(*	alloc )(void *ctx, size_t len, uint8_t alignment, uintptr_t ret_addr)
bool(*	resize )(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr)
void *(*	remap )(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr)
void(*	free )(void *ctx, void *memory, size_t memory_len, uint8_t alignment, uintptr_t ret_addr)

Detailed Description

Function table for custom memory allocator operations.

This vtable defines the interface for a custom memory allocator. All function pointers must be valid and non-NULL.

If you're not going to use a custom allocator, you can ignore all of this. All functions that take an allocator pointer allow NULL to use a default allocator.

The interface is based on the Zig allocator interface. I'll say up front that it is easy to look at this interface and think "wow, this is really overcomplicated". The reason for this complexity is well thought out by the Zig folks, and it enables a diverse set of allocation strategies as shown by the Zig ecosystem. As a consolation, please note that many of the arguments are only needed for advanced use cases and can be safely ignored in simple implementations. For example, if you look at the Zig implementation of the libc allocator in lib/std/heap.zig (search for CAllocator), you'll see it is very simple.

We chose to align with the Zig allocator interface because:

1. It is a proven interface that serves a wide variety of use cases in the real world via the Zig ecosystem. It's shown to work.
2. Our core implementation itself is Zig, and this lets us very cheaply and easily convert between C and Zig allocators.

NOTE(mitchellh): In the future, we can have default implementations of resize/remap and allow those to be null.

Definition at line 83 of file allocator.h.

Field Documentation

alloc

void *(* alloc) (void *ctx, size_t len, uint8_t alignment, uintptr_t ret_addr)

Return a pointer to len bytes with specified alignment, or return NULL indicating the allocation failed.

Parameters

ctx	The allocator context
len	Number of bytes to allocate
alignment	Required alignment for the allocation. Guaranteed to be a power of two between 1 and 16 inclusive.
ret_addr	First return address of the allocation call stack (0 if not provided)

Returns

Pointer to allocated memory, or NULL if allocation failed

Definition at line 95 of file allocator.h.

free

void(* free) (void *ctx, void *memory, size_t memory_len, uint8_t alignment, 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.

Parameters

ctx	The allocator context
memory	Pointer to the memory block to free
memory_len	Size of the memory block
alignment	Alignment (must match original allocation)
ret_addr	First return address of the allocation call stack (0 if not provided)

Definition at line 158 of file allocator.h.

remap

void *(* remap) (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.

Parameters

ctx	The allocator context
memory	Pointer to the memory block to remap
memory_len	Current size of the memory block
alignment	Alignment (must match original allocation)
new_len	New requested size
ret_addr	First return address of the allocation call stack (0 if not provided)

Returns

Pointer to resized memory (may be relocated), or NULL if manual copy is needed

Definition at line 142 of file allocator.h.

resize

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 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.

Parameters

ctx	The allocator context
memory	Pointer to the memory block to resize
memory_len	Current size of the memory block
alignment	Alignment (must match original allocation)
new_len	New requested size
ret_addr	First return address of the allocation call stack (0 if not provided)

Returns

true if resize was successful in-place, false if relocation would be required

Definition at line 115 of file allocator.h.

---

The documentation for this struct was generated from the following file:

• allocator.h