Allocators

Run the library on your own memory allocator. More...

Detailed Description

Run the library on your own memory allocator.

An allocator is the set of functions libghostty-vt calls to get and free memory.

Most programs never need this. Any function that takes a const GhosttyAllocator* accepts NULL, which selects the default allocator. You only need your own to run the library on memory you control.

Example

  Stats stats = {0};
  GhosttyAllocator allocator = {
      .ctx = &stats,
      .vtable = &my_vtable,
  };
 
  /* The terminal keeps a pointer to the allocator, so `allocator` must
   * stay alive until ghostty_terminal_free(). */
  GhosttyTerminal terminal;
  if (ghostty_terminal_new(&allocator, &terminal, 80, 24) !=
      GHOSTTY_SUCCESS) {
    fprintf(stderr, "ghostty_terminal_new failed\n");
    return 1;
  }

Full program: c-vt-allocator/src/main.c

See Memory for what the default is, how to write your own allocator, and how to free memory the library gives you.

Typedefs
typedef void *(*	GhosttyAllocatorAllocFn) (void *ctx, size_t len, uint8_t alignment, uintptr_t ret_addr)
typedef bool(*	GhosttyAllocatorResizeFn) (void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr)
typedef void *(*	GhosttyAllocatorRemapFn) (void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr)
typedef void(*	GhosttyAllocatorFreeFn) (void *ctx, void *memory, size_t memory_len, uint8_t alignment, uintptr_t ret_addr)

Functions
GHOSTTY_API uint8_t *	ghostty_alloc (const GhosttyAllocator *allocator, size_t len)
GHOSTTY_API void	ghostty_free (const GhosttyAllocator *allocator, uint8_t *ptr, size_t len)

Data Structures
struct	GhosttyAllocatorVtable
struct	GhosttyAllocator

Typedef Documentation

GhosttyAllocatorAllocFn

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

Allocate a block of memory.

This is the alloc function of a GhosttyAllocatorVtable. It's required.

Parameters

ctx	The allocator's context pointer
len	Number of bytes to allocate
alignment	The block's address must be a multiple of 1 << alignment bytes. See Alignment.
ret_addr	Address of the requesting code, or 0. Safe to ignore.

Returns

The new block, or NULL if it could not be allocated

Definition at line 50 of file allocator.h.

GhosttyAllocatorFreeFn

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

Free a block.

This is the free function of a GhosttyAllocatorVtable. It's required. After it 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 140 of file allocator.h.

GhosttyAllocatorRemapFn

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

This is the remap function of a GhosttyAllocatorVtable. It's optional, and leaving it NULL is the same as always returning NULL.

Unlike GhosttyAllocatorResizeFn, this may return a new address, for example after remapping virtual memory pages. The block must hold the old contents at that address, and the old address 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, 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 124 of file allocator.h.

GhosttyAllocatorResizeFn

typedef bool(* GhosttyAllocatorResizeFn) (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.

This is the resize function of a GhosttyAllocatorVtable. It's optional, and leaving it NULL is the same as always returning 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.

For example, an arena that hands out memory from one buffer can resize its most recent block, because nothing comes after it:

typedef struct {
  uint8_t* base;
  size_t used;
  size_t capacity;
} Arena;
 
static bool arena_resize(void* ctx, void* memory, size_t memory_len,
                         uint8_t alignment, size_t new_len,
                         uintptr_t ret_addr) {
  (void)alignment;
  (void)ret_addr;
  Arena* arena = ctx;
  size_t start = (size_t)((uint8_t*)memory - arena->base);
 
  // Only the last block can change size in place.
  if (start + memory_len != arena->used) return false;
  if (start + new_len > arena->capacity) return false;
 
  arena->used = start + new_len;
  return true;
}

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 99 of file allocator.h.

Function Documentation

ghostty_alloc()

GHOSTTY_API uint8_t * ghostty_alloc	(	const GhosttyAllocator *	allocator,
		size_t	len )

Allocate a buffer of len bytes.

Uses the provided allocator, or the default allocator if NULL is passed. The returned buffer must be freed with ghostty_free() using the same allocator.

Parameters

allocator	Pointer to the allocator to use, or NULL for the default
len	Number of bytes to allocate

Returns

Pointer to the allocated buffer, or NULL if len is zero or allocation failed

Examples

c-vt-kitty-graphics/src/main.c.

ghostty_free()

GHOSTTY_API void ghostty_free	(	const GhosttyAllocator *	allocator,
		uint8_t *	ptr,
		size_t	len )

Free memory that was allocated by a libghostty-vt function.

Use this to free buffers returned by functions such as ghostty_formatter_format_alloc(). Pass the same allocator that was used for the allocation, or NULL if the default allocator was used.

Use this instead of the C free(), which can use a different heap than the library. See Allocating and Freeing Buffers for why.

Passing a NULL ptr does nothing.

Parameters

allocator	Pointer to the allocator that was used to allocate the memory, or NULL if the default allocator was used
ptr	Pointer to the memory to free (may be NULL)
len	Length of the allocation in bytes (must match the original allocation size)

Examples

c-vt-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-hello/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, c-vt-snapshot/src/main.c, and c-vt-stream/src/main.c.