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)
void *	reserved [4]

Detailed Description

The functions that make up a custom allocator.

alloc and free are required. resize and remap are optional, and when they are NULL the library grows memory by allocating a new block, copying, and freeing the old one. See Writing a Custom Allocator for a complete example and Alignment for an explanation of alignment.

Every function receives the ctx pointer from the GhosttyAllocator it belongs to. When the library resizes, remaps, or frees memory, it always passes the same alignment it used for the original allocation and the current length of the block, so your allocator does not need to record either.

Every function also receives ret_addr, the address of the code that requested the memory, or 0 if it is unknown. Allocators that track leaks or report where memory came from can use it. Most allocators ignore it.

Initialize the whole struct to zero before setting the fields you use, so the reserved slots are NULL.

The interface matches Zig's std.mem.Allocator. The library is written in Zig, so this lets it use your allocator directly, and it is an interface already proven by a wide range of allocators in the Zig ecosystem. Simple allocators can ignore most of the arguments. Zig's own libc allocator (CAllocator in lib/std/heap.zig) is a good short reference.

Examples

c-vt-allocator/src/main.c.

Definition at line 67 of file allocator.h.

Field Documentation

alloc

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

Allocate len bytes aligned to 1 << alignment bytes.

Required.

Parameters

ctx	The allocator's context pointer
len	Number of bytes to allocate
alignment	Alignment as a power of two exponent. See Alignment for details.
ret_addr	Address of the requesting code, or 0. Safe to ignore.

Returns

Pointer to the new memory, or NULL if it could not be allocated

Definition at line 81 of file allocator.h.

free

void(* free) (void *ctx, void *memory, size_t memory_len, uint8_t alignment, uintptr_t ret_addr)

Free a block.

Required. After this returns, the library never uses memory again.

Parameters

ctx	The allocator's context pointer
memory	Start of a block returned by alloc or remap
memory_len	Current length of the block
alignment	The alignment the block was allocated with
ret_addr	Address of the requesting code, or 0. Safe to ignore.

Definition at line 138 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)

Grow or shrink a block, moving it if that is cheaper than a copy.

Optional. A NULL remap is the same as one that always returns NULL.

Return a pointer to a block of new_len bytes holding the old contents. It may be the same address or a new one, for example after remapping virtual memory pages. If you return a new address, the old one is no longer valid.

Return NULL when the only way to do it would be to allocate, copy, and free. The library does that itself in that case, so there is no benefit in doing it here.

Parameters

ctx	The allocator's context pointer
memory	Start of a block returned by alloc or remap
memory_len	Current length of the block
alignment	The alignment the block was allocated with
new_len	Requested length, always greater than zero
ret_addr	Address of the requesting code, or 0. Safe to ignore.

Returns

The resized block, or NULL to let the library copy instead

Definition at line 125 of file allocator.h.

reserved

void* reserved[4]

Reserved for future versions. Must be NULL.

These slots let a future release add new allocator functions without changing the size of this struct. The library ignores any slot it does not know about, so leaving them NULL keeps your code working with future versions.

Debug builds of the library stop with an error if a reserved slot is not NULL, to catch a vtable that was not zero-initialized.

Definition at line 151 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)

Try to grow or shrink a block without moving it.

Optional. A NULL resize is the same as one that always returns false.

Return true only if the block at memory is now new_len bytes long at the same address. Return false if that would require moving it. The library then decides whether to allocate a new block and copy.

Parameters

ctx	The allocator's context pointer
memory	Start of a block returned by alloc or remap
memory_len	Current length of the block
alignment	The alignment the block was allocated with
new_len	Requested length, always greater than zero
ret_addr	Address of the requesting code, or 0. Safe to ignore.

Returns

true if the block was resized in place, false otherwise

Definition at line 101 of file allocator.h.

---

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

• allocator.h