facil.io
Utilities & Parsers

#Memory Allocator

c
#define FIO_MEMORY_NAME fio
#include "fio-stl.h"

A concurrent, per-arena memory allocator that groups objects with similar lifetimes. It tries to keep related allocations in the same chunk so cleanup is cheap and locality is decent. Define FIO_MEMORY_DISABLE to route everything to the system malloc/free instead.

The prefix fio comes from FIO_MEMORY_NAME. All public function names are built with FIO_NAME(FIO_MEMORY_NAME, ...), so a custom prefix produces my_malloc, my_free, and so on.

The module also sets the temporary allocator macros (FIO_MEM_REALLOC_, FIO_MEM_FREE_, FIO_MEM_REALLOC_IS_SAFE_, FIO_MEM_ALIGNMENT_SIZE_) for any facil.io type defined in the same include scope.

Note: FIO_MALLOC is a shortcut that defines this allocator with prefix fio and general-purpose tuning.

#Core API

#fio_malloc

c
SFUNC void *FIO_MEM_ALIGN_NEW FIO_NAME(FIO_MEMORY_NAME, malloc)(size_t size);

Allocates size bytes aligned to FIO_MEMORY_ALIGN_SIZE. Memory is zeroed if FIO_MEMORY_INITIALIZE_ALLOCATIONS is enabled. Allocations above the arena limit use big-block mode or mmap.

Parameters:

  • size — bytes to allocate.

Returns: pointer to allocated memory, or NULL on failure.

#fio_calloc

c
SFUNC void *FIO_MEM_ALIGN_NEW FIO_NAME(FIO_MEMORY_NAME,
                                       calloc)(size_t size_per_unit,
                                               size_t unit_count);

Equivalent to fio_malloc(size_per_unit * unit_count).

#fio_realloc

c
SFUNC void *FIO_MEM_ALIGN FIO_NAME(FIO_MEMORY_NAME, realloc)(void *ptr,
                                                             size_t new_size);

Reallocates ptr to new_size. Copy-free expansion is only attempted for large allocations. Prefer fio_realloc2 for predictable zeroing.

Parameters:

  • ptr — existing allocation, or NULL.
  • new_size — requested new size.

Returns: pointer to the new block, or NULL on failure.

#fio_realloc2

c
SFUNC void *FIO_MEM_ALIGN FIO_NAME(FIO_MEMORY_NAME, realloc2)(void *ptr,
                                                              size_t new_size,
                                                              size_t copy_len);

Reallocates ptr to new_size, copying at most copy_len bytes. Memory beyond copy_len is zeroed when FIO_MEMORY_INITIALIZE_ALLOCATIONS is enabled.

Parameters:

  • ptr — existing allocation, or NULL.
  • new_size — requested new size.
  • copy_len — maximum bytes to copy from the old block.

Returns: pointer to the new block, or NULL on failure.

#fio_free

c
SFUNC void FIO_NAME(FIO_MEMORY_NAME, free)(void *ptr);

Frees memory allocated by this allocator. Freeing a pointer from a different allocator, or after cleanup, is undefined behavior.

#fio_mmap

c
SFUNC void *FIO_MEM_ALIGN_NEW FIO_NAME(FIO_MEMORY_NAME, mmap)(size_t size);

Allocates directly from the system with mmap semantics. Use this for large, long-lived objects. The allocation is slower but avoids arena bookkeeping.

Parameters:

  • size — bytes to allocate.

Returns: pointer to allocated memory, or NULL on failure.

#fio_malloc_after_fork

c
SFUNC void FIO_NAME(FIO_MEMORY_NAME, malloc_after_fork)(void);

Reinitializes allocator locks after fork in the child process. Best effort only: forking a multi-threaded process is unsafe. Prefer calling fio_state_callback_force(FIO_CALL_IN_CHILD); to reset all registered allocators.

#fio_realloc_is_safe

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, realloc_is_safe)(void);

Returns non-zero if the allocator zeroes allocations, which makes fio_realloc2 safe for the uncopied tail.

#Aligned Allocation API

The aligned API requests a minimum pointer alignment. fio_malloc_aligned and fio_calloc_aligned are thin wrappers around fio_realloc_aligned, which is the single entry point.

#fio_realloc_aligned

c
SFUNC void *FIO_MEM_ALIGN FIO_NAME(FIO_MEMORY_NAME,
                                   realloc_aligned)(void *ptr,
                                                    size_t new_size,
                                                    size_t copy_len,
                                                    size_t alignment);

Reallocates ptr to new_size (copying at most copy_len bytes, like fio_realloc2), guaranteeing the returned pointer is aligned to at least alignment.

The alignment argument is normalized:

  • 0 selects the allocator default (FIO_MEMORY_ALIGN_SIZE).
  • Non power-of-2 values are rounded down to the nearest power of 2.
  • The effective alignment is the maximum of the (rounded) request, the current alignment of ptr, and FIO_MEMORY_ALIGN_SIZE — alignment never regresses across a realloc.
  • Values above FIO_MEMORY_SYS_ALLOCATION_SIZE fail: returns NULL and sets errno to EINVAL (debug builds also trip FIO_ASSERT_DEBUG).

In-place growth only occurs when the existing pointer already satisfies the requested alignment; otherwise the data is copied to a newly aligned block.

realloc_aligned(NULL, size, 0, alignment) allocates (like malloc_aligned), and realloc_aligned(ptr, 0, copy_len, alignment) frees ptr.

#fio_malloc_aligned

c
SFUNC void *FIO_MEM_ALIGN_NEW FIO_NAME(FIO_MEMORY_NAME,
                                       malloc_aligned)(size_t size,
                                                       size_t alignment);

Equivalent to fio_realloc_aligned(NULL, size, 0, alignment). A zero size returns the shared zero-allocation pointer (aligned only to FIO_MEMORY_ALIGN_SIZE), which may be freed or realloc'd normally.

#fio_calloc_aligned

c
SFUNC void *FIO_MEM_ALIGN_NEW FIO_NAME(FIO_MEMORY_NAME,
                                       calloc_aligned)(size_t size_per_unit,
                                                       size_t unit_count,
                                                       size_t alignment);

Same as fio_malloc_aligned(size_per_unit * unit_count, alignment), but zeroes the (rounded) allocation. Returns NULL on size overflow.

#fio_alloc_size

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, alloc_size)(size_t minimum_bytes);

Returns the number of usable bytes the allocator actually reserves for a request of minimum_bytes (the size class): rounded up to FIO_MEMORY_ALIGN_SIZE for arena/big-block allocations, and to whole pages (minus the header offset) for page-backed ones. Alignment padding is reserved in addition to the returned value. With FIO_MEMORY_DISABLE the system allocator exposes no rounding guarantee and minimum_bytes is returned unchanged.

#Alignment abstraction macros

c
FIO_MEM_REALLOC_ALIGNED(ptr, old_size, new_size, copy_len, alignment)
FIO_MEM_FREE_ALIGNED(ptr, size)
FIO_MEM_ALLOC_SIZE(size)

FIO_MEM_REALLOC_ALIGNED mirrors FIO_MEM_REALLOC with an added alignment argument and assigns the result to ptr (test with FIO_ASSERT_ALLOC(ptr) after the call, restoring a saved copy on failure). FIO_MEM_FREE_ALIGNED releases memory obtained through the aligned API, and FIO_MEM_ALLOC_SIZE mirrors fio_alloc_size.

The macros route to the active allocator, exactly like FIO_MEM_REALLOC does: the fio allocator when it was included (H___FIO_MALLOC___H), or portable system-allocator fallbacks otherwise. Template-local variants (FIO_MEM_REALLOC_ALIGNED_, FIO_MEM_FREE_ALIGNED_) exist for FIO_MEMORY_NAME template scope, mirroring FIO_MEM_REALLOC_ / FIO_MEM_FREE_.

Pairing rule: with the fio allocator, free accepts any pointer returned by the aligned API (interior pointers included), so FIO_MEM_FREE_ALIGNED is identical to FIO_MEM_FREE. Under FIO_MEMORY_DISABLE on Windows the aligned API uses _aligned_malloc / _aligned_realloc, whose memory must be released with FIO_MEM_FREE_ALIGNED (_aligned_free) — plain free is heap corruption. On POSIX both map to free. Custom allocators that stash alignment bookkeeping near the returned pointer should hook the macro pair, not the fio functions.

#Alignment guarantees per configuration

Configuration Default alignment Aligned API backend Max alignment
fio allocator (any OS) FIO_MEMORY_ALIGN_SIZE (64) interior-pointer slice / big-block / page-backed FIO_MEMORY_SYS_ALLOCATION_SIZE
FIO_MEMORY_DISABLE, POSIX _Alignof(max_align_t) posix_memalign + free FIO_MEMORY_SYS_ALLOCATION_SIZE
FIO_MEMORY_DISABLE, Windows _Alignof(max_align_t) (16) _aligned_malloc / _aligned_realloc / _aligned_free FIO_MEMORY_SYS_ALLOCATION_SIZE
FIO_MEMORY_DISABLE, other _Alignof(max_align_t) over-allocation with stashed raw pointer FIO_MEMORY_SYS_ALLOCATION_SIZE

When FIO_MALLOC_OVERRIDE_SYSTEM is defined, the libc aligned-allocation family is overridden as well (aligned_alloc, posix_memalign, and on Windows _aligned_malloc / _aligned_realloc / _aligned_free), so libc-aligned pointers never reach the fio allocator (and vice versa).

#Configuration Macros

#FIO_MEMORY_NAME

c
#define FIO_MEMORY_NAME fio

Required prefix for the allocator's public symbols. Must be defined before including the header.

#FIO_MALLOC

c
#define FIO_MALLOC

Shortcut that defines the allocator with prefix fio and tunes it for general use. It also redefines FIO_MEM_REALLOC, FIO_MEM_FREE, FIO_MEM_REALLOC_IS_SAFE, and FIO_MEM_ALIGNMENT_SIZE.

#FIO_MEMORY_DISABLE

c
#define FIO_MEMORY_DISABLE

Bypasses the custom allocator and routes all allocations to the system malloc/free.

#FIO_MEMORY_ALIGN_LOG

c
#define FIO_MEMORY_ALIGN_LOG 6

Log2 of the allocation alignment. Clamped to the range 3–10 (8 to 1024 bytes). Default is 6 (64 bytes).

#FIO_MEMORY_SYS_ALLOCATION_SIZE_LOG

c
#define FIO_MEMORY_SYS_ALLOCATION_SIZE_LOG 21

Log2 of the chunk size allocated from the system. Clamped to 17–24. Default is 21 (~2 MB).

#FIO_MEMORY_BLOCKS_PER_ALLOCATION_LOG

c
#define FIO_MEMORY_BLOCKS_PER_ALLOCATION_LOG 2

Log2 of the number of blocks per system chunk. Range 0–4. Affects fragmentation and the threshold for big allocations.

#FIO_MEMORY_ENABLE_BIG_ALLOC

c
#define FIO_MEMORY_ENABLE_BIG_ALLOC 1

When enabled, large allocations can consume an entire chunk as a single big block. May increase fragmentation for long-lived objects.

#FIO_MEMORY_ARENA_COUNT

c
#define FIO_MEMORY_ARENA_COUNT -1

Number of arenas. Negative or zero means dynamic selection based on CPU core count, capped by FIO_MEMORY_ARENA_COUNT_MAX and fallback FIO_MEMORY_ARENA_COUNT_FALLBACK.

#FIO_MEMORY_ARENA_COUNT_FALLBACK

c
#define FIO_MEMORY_ARENA_COUNT_FALLBACK 24

Default arena count when dynamic CPU detection fails.

#FIO_MEMORY_ARENA_COUNT_MAX

c
#define FIO_MEMORY_ARENA_COUNT_MAX 64

Upper bound for dynamic arena count.

#FIO_MEMORY_USE_THREAD_MUTEX

c
#define FIO_MEMORY_USE_THREAD_MUTEX 0

When 1, arenas protect themselves with pthread mutexes instead of spinlocks. Default is 1 when FIO_MEMORY_ARENA_COUNT is positive.

#FIO_MEMORY_INITIALIZE_ALLOCATIONS

c
#define FIO_MEMORY_INITIALIZE_ALLOCATIONS \
        FIO_MEMORY_INITIALIZE_ALLOCATIONS_DEFAULT

When 1, allocations return zeroed memory and realloc2 zeroes uncopied bytes. Default is 1.

#FIO_MEMORY_INITIALIZE_ALLOCATIONS_DEFAULT

c
#define FIO_MEMORY_INITIALIZE_ALLOCATIONS_DEFAULT 1

Default value for FIO_MEMORY_INITIALIZE_ALLOCATIONS.

#FIO_MEMORY_CACHE_SLOTS

c
#define FIO_MEMORY_CACHE_SLOTS 4

Number of freed chunks to keep cached before returning memory to the system.

#FIO_MEMORY_WARMUP

c
#define FIO_MEMORY_WARMUP 0

If set to a positive number, that many arenas pre-allocate a block at startup. Usually best left at 0.

#FIO_MEM_SYS_ALLOC, FIO_MEM_SYS_REALLOC, FIO_MEM_SYS_FREE

c
#define FIO_MEM_SYS_ALLOC(pages, alignment_log) /* ... */
#define FIO_MEM_SYS_REALLOC(ptr, old_pages, new_pages, alignment_log) /* ... */
#define FIO_MEM_SYS_FREE(ptr, pages) /* ... */

Override all three to replace the system allocation backend. Alignment is essential and may be large.

#Introspection

These functions are exposed for debugging. Treat them as unstable.

#fio_malloc_arenas

c
SFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_arenas)(void);

Returns the number of arenas.

#fio_malloc_block_size

c
SFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_block_size)(void);

Returns the block size used for arena allocations.

#fio_malloc_sys_alloc_size

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_sys_alloc_size)(void);

Returns the system chunk size in bytes.

#fio_malloc_cache_slots

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_cache_slots)(void);

Returns the configured number of cache slots.

#fio_malloc_alignment

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_alignment)(void);

Returns the allocation alignment in bytes.

#fio_malloc_alignment_log

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_alignment_log)(void);

Returns log2 of the allocation alignment.

#fio_malloc_alloc_limit

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_alloc_limit)(void);

Returns the size above which allocations bypass arena blocks.

#fio_malloc_arena_alloc_limit

c
FIO_IFUNC size_t FIO_NAME(FIO_MEMORY_NAME, malloc_arena_alloc_limit)(void);

Returns the arena block size limit.

#fio_malloc_print_state

c
SFUNC void FIO_NAME(FIO_MEMORY_NAME, malloc_print_state)(void);

Prints allocator state to stderr.

#fio_malloc_print_free_block_list

c
SFUNC void FIO_NAME(FIO_MEMORY_NAME, malloc_print_free_block_list)(void);

Prints the free-block list to stderr.

#fio_malloc_print_settings

c
SFUNC void FIO_NAME(FIO_MEMORY_NAME, malloc_print_settings)(void);

Prints allocator settings to stderr.

#Example

c
#define FIO_MALLOC
#include "fio-stl.h"

int main(void) {
  char *buf = fio_malloc(256);
  if (!buf) return -1;

  fio_memcpy(buf, "hello", 5);
  fprintf(stderr, "%s\n", buf);

  char *buf2 = fio_realloc2(buf, 512, 5);
  if (!buf2) {
    fio_free(buf);
    return -1;
  }
  buf = buf2;

  fio_free(buf);
  return 0;
}