LIBFYAML-MISC(3)

NAME
libfyaml-misc - libfyaml miscellaneous API

UTILITIES

This header provides the low-level building blocks shared by all other libfyaml public headers. It has no libfyaml dependencies of its own and is safe to include in isolation.

Platform portability

•   ssize_t shim for MSVC / Windows toolchains

•   struct iovec shim for Windows (sys/uio.h substitute)

•   FY_EXPORT / FY_DEPRECATED / FY_FORMAT — symbol visibility and compiler-attribute portability macros

•   FY_UNUSED, FY_ALWAYS_INLINE, FY_DEBUG_UNUSED — compiler hint wrappers with safe fallbacks on non-GCC/Clang toolchains

•   FY_CONSTRUCTOR / FY_DESTRUCTOR — GCC-style constructor/destructor attributes with availability guards (FY_HAS_CONSTRUCTOR, FY_HAS_DESTRUCTOR)

    Core constants and sentinel values

•   FY_BIT(x) — single-bit mask (1U << x)

•   FY_NT — sentinel meaning “null-terminated”; pass as a length argument to indicate that the string length should be inferred via strlen

    Memory helpers

•   FY_ALLOCA_COPY_FREE / FY_ALLOCA_COPY_FREE_NO_NULL — copy a malloc-returned string onto the stack and immediately free the heap allocation; produces an alloca-lifetime copy in a single expression

•   fy_vsprintfa / fy_sprintfa — printf-style formatting into a stack-allocated (alloca) buffer; the result is valid for the lifetime of the enclosing function

    Container and array helpers

•   container_of — recover a pointer to an enclosing struct from a pointer to one of its members

•   ARRAY_SIZE — number of elements in a stack-allocated array

    Type safety and compile-time checks

•   FY_SAME_TYPE / FY_CHECK_SAME_TYPE — assert two expressions share the same C type (wraps __builtin_types_compatible_p with a fallback)

•   FY_COMPILE_ERROR_ON_ZERO — produce a compile-time error when the argument evaluates to zero; used for macro-level static assertions

    Overflow-safe arithmetic

•   FY_ADD_OVERFLOW, FY_SUB_OVERFLOW, FY_MUL_OVERFLOW — wrappers around __builtin_*_overflow with portable fallback implementations

    Miscellaneous

•   FY_IMPOSSIBLE_ABORT — mark unreachable code paths; aborts at runtime

•   FY_STACK_SAVE / FY_STACK_RESTORE — save and restore the stack pointer for alloca-based temporary arenas

•   Lambda / closure macros and a CPP metaprogramming framework for building variadic generic APIs

•   Diagnostic helpers and floating-point precision constants

    This section implements a portable FY_CPP_* macro toolkit that enables applying an operation to every argument in a __VA_ARGS__ list — the equivalent of a compile-time map() function.

    The core challenge: The C preprocessor does not support recursion. A macro cannot call itself. The standard workaround is deferred evaluation: a macro is “postponed” so that it is not expanded in the current scan pass, only in a future one. Multiple passes are forced by the FY_CPP_EVALn ladder which re-expands the token stream a power-of-two number of times.

    Evaluation levels (FY_CPP_EVAL1 .. FY_CPP_EVAL):

•   FY_CPP_EVAL1 — one pass (no re-expansion)

•   FY_CPP_EVAL2 — 2 passes

•   FY_CPP_EVAL4 — 4 passes

•   FY_CPP_EVAL8 — 8 passes

•   FY_CPP_EVAL16 — 16 passes (GCC only; Clang craps out at 8)

•   FY_CPP_EVAL — full depth (32 passes on GCC, 16 on Clang)

    Each doubling allows mapping over twice as many arguments. FY_CPP_EVAL supports lists of up to ~32 elements (GCC) or ~16 elements (Clang) in practice.

    Argument accessors — extract positional arguments from __VA_ARGS__:

•   FY_CPP_FIRST(...) — first argument (0 if list is empty)

•   FY_CPP_SECOND(...) — second argument

•   FY_CPP_THIRD(...) — third argument

•   FY_CPP_FOURTH(...) — fourth argument

•   FY_CPP_FIFTH(...) — fifth argument

•   FY_CPP_SIXTH(...) — sixth argument

•   FY_CPP_REST(...) — all arguments after the first (empty if < 2)

    Map operations:

•   FY_CPP_MAP(macro, ...) — expand macro(x) for each argument x.

•   FY_CPP_MAP2(a, macro, ...) — expand macro(a, x) for each x, threading a fixed first argument a through every call.

    Utility:

•   FY_CPP_VA_COUNT(...) — number of arguments (integer expression).

•   FY_CPP_VA_ITEMS(_type, ...) — compound-literal array of _type from varargs.

•   FY_CPP_EMPTY() — deferred empty token (used to postpone macros).

•   FY_CPP_POSTPONE1(macro) — postpone a one-argument macro one pass.

•   FY_CPP_POSTPONE2(a, macro) — postpone a two-argument macro one pass.

    Short-name mode (FY_CPP_SHORT_NAMES):

    By default the implementation uses abbreviated internal names (_E1, _FM, etc.) to reduce token-expansion buffer pressure. Define FY_CPP_SHORT_NAMES_DEBUG before including this header to force the original long-name implementation (FY_CPP_EVAL1, _FY_CPP_MAP_ONE, etc.) which is easier to read in expansion traces.

    Example:

        // Count and collect variadic integer arguments into a C array:
        int do_sum(int count, int *items) { ... }
        #define do_sum_macro(...) \
            do_sum(FY_CPP_VA_COUNT(__VA_ARGS__), \
                   FY_CPP_VA_ITEMS(int, __VA_ARGS__))
        // do_sum_macro(1, 2, 5, 100) expands to:
        // do_sum(4, ((int [4]){ 1, 2, 5, 100 }))

    Portable wrappers around GCC/Clang #pragma GCC diagnostic directives. Use FY_DIAG_PUSH() and FY_DIAG_POP() to bracket a region where a specific warning is suppressed:

        FY_DIAG_PUSH
        FY_DIAG_IGNORE_ARRAY_BOUNDS
        ... code that triggers -Warray-bounds ...
        FY_DIAG_POP

    On compilers other than GCC/Clang all macros in this group expand to nothing.

    Portable wrappers for the mantissa-digit and decimal-digit counts of float, double, and long double. Each macro tries three sources in order:

1.  The standard <float.h> macro (e.g. FLT_MANT_DIG).

2.  The GCC/Clang predefined macro (e.g. __FLT_MANT_DIG__).

3.  A conservative hard-coded fallback.

    These constants are used when formatting floating-point values as YAML scalars to ensure round-trip fidelity.

  macro __has_builtin

__has_builtin(x)
    Fallback for compilers that do not provide __has_builtin.

Parameters

•   x – The builtin name to query.

  Description

Always evaluates to 0 (false) so that all #if __has_builtin(...) guards safely fall back to the portable implementation.

  Return

0.

  macro FY_BIT

FY_BIT(x)
    Produce an unsigned bitmask with bit x set.

Parameters

•   x – Zero-based bit position (0–31 for a 32-bit result).

  Return

1U << x.

  macro FY_NT

FY_NT()
    Sentinel value meaning “null-terminated; compute length at runtime”.

  Description

Pass as the len argument to any libfyaml function that accepts a (const char *str, size_t len) pair to indicate that str is a NUL-terminated C string whose length should be determined with strlen().

Value: (size_t)-1

  macro FY_EXPORT

FY_EXPORT()
    Mark a symbol as part of the shared-library public ABI.

  Description

On GCC/Clang (version >= 4) expands to __attribute__((visibility("default"))), overriding -fvisibility=hidden for the annotated symbol. On other compilers expands to nothing (all symbols are visible by default).

  macro FY_DEPRECATED

FY_DEPRECATED()
    Mark a function or variable as deprecated.

  Description

On GCC/Clang expands to __attribute__((deprecated)), causing a compile-time warning whenever the annotated symbol is used. On other compilers expands to nothing.

  macro FY_FORMAT

FY_FORMAT(_t, _x, _y)
    Annotate a function with printf-style format checking.

Parameters

•   _t – Format type token (e.g. printf, scanf, strftime).

•   _x – 1-based index of the format-string parameter.

•   _y – 1-based index of the first variadic argument (0 for va_list wrappers).

  Description

On GCC/Clang expands to __attribute__((format(_t, _x, _y))), enabling the compiler to type-check the format string and variadic arguments.

  macro FY_ALLOCA_COPY_FREE

FY_ALLOCA_COPY_FREE(_str, _len)
    Copy a heap string onto the stack and free the original.

Parameters

•   _str – Heap-allocated string to copy and free (may be NULL).

•   _len – Length in bytes, or FY_NT to use strlen().

  Expands to a statement expression that

1.  Copies _str (up to _len bytes, or the full NUL-terminated length when _len is FY_NT) into a NUL-terminated stack buffer via alloca().

2.  Calls free(@_str) to release the heap allocation.

3.  Evaluates to a const char * pointing to the stack copy.

    When _str is NULL the macro evaluates to NULL and performs no copy or free.

    The stack buffer is valid only for the lifetime of the enclosing function. Do not call this in a loop — each invocation grows the stack frame.

  Return

const char * to the stack copy, or NULL if _str was NULL.

  macro FY_ALLOCA_COPY_FREE_NO_NULL

FY_ALLOCA_COPY_FREE_NO_NULL(_str, _len)
    Like FY_ALLOCA_COPY_FREE() but returns “” for NULL.

Parameters

•   _str – Heap-allocated string to copy and free (may be NULL).

•   _len – Length in bytes, or FY_NT to use strlen().

  Description

Identical to FY_ALLOCA_COPY_FREE but substitutes an empty string literal "" when _str is NULL, so callers never receive a NULL pointer.

  Return

const char * to the stack copy, or "" if _str was NULL.

  macro container_of

container_of(ptr, type, member)
    Recover a pointer to a containing struct from a member pointer.

Parameters

•   ptr – Pointer to the member field.

•   type – Type of the containing struct.

•   member – Name of the member field within type.

  Description

Given a pointer ptr to a field named member inside a struct of type type, returns a pointer to the enclosing type instance.

Uses __typeof__ to catch type mismatches at compile time (GCC/Clang).

  Return

Pointer to the containing struct of type type.

  macro ARRAY_SIZE

ARRAY_SIZE(x)
    Compute the number of elements in a stack-allocated array.

Parameters

•   x – The array expression.

  Description

Evaluates to a compile-time constant. Only valid for arrays with a known size at compile time (not pointers or VLAs).

  Return

Number of elements, as a size_t.

  macro FY_UNUSED

FY_UNUSED()
    Suppress “unused variable/parameter” warnings.

  Description

On GCC/Clang (version >= 4) expands to __attribute__((unused)). On other compilers expands to nothing.

Use on parameters or local variables that are intentionally unreferenced, e.g. in debug-only code paths.

  macro FY_CONSTRUCTOR

FY_CONSTRUCTOR()
    Run a function automatically before main().

  Description

On GCC/Clang expands to __attribute__((constructor)). Also defines FY_HAS_CONSTRUCTOR so callers can detect support at compile time. On other compilers expands to nothing and FY_HAS_CONSTRUCTOR is not defined.

  macro FY_DESTRUCTOR

FY_DESTRUCTOR()
    Run a function automatically after main() (or on exit()).

  Description

On GCC/Clang expands to __attribute__((destructor)). Also defines FY_HAS_DESTRUCTOR so callers can detect support at compile time. On other compilers expands to nothing and FY_HAS_DESTRUCTOR is not defined.

  macro FY_DEBUG_UNUSED

FY_DEBUG_UNUSED()
    Mark a variable as potentially unused in non-debug builds.

  Description

Expands to __attribute__((unused)) on GCC/Clang when NDEBUG is defined, silencing warnings for variables that are only referenced inside assert() calls (which disappear in release builds). In debug builds (NDEBUG not set) expands to nothing.

  macro FY_IMPOSSIBLE_ABORT

FY_IMPOSSIBLE_ABORT(void)
    Assert that an unreachable code path has been reached.

Parameters

•   void – no arguments

  Description

Calls assert(0) followed by abort() to terminate the process immediately. Use to mark code paths that must never execute in a correct program, such as the default branch of a switch that covers all enum values.

The double invocation ensures termination even when assertions are disabled (NDEBUG).

  macro FY_COMPILE_ERROR_ON_ZERO

FY_COMPILE_ERROR_ON_ZERO(_e)
    Trigger a compile error if expression _e is zero.

Parameters

•   _e – Compile-time expression that must be non-zero.

  Description

Evaluates _e at compile time. If _e is zero, sizeof(char[-1]) is ill-formed and the build fails. If _e is non-zero, the expression is a no-op void cast.

Prefer FY_CHECK_SAME_TYPE or static_assert for clearer error messages; use this primitive when a compile-time boolean is needed in a macro context.

  macro FY_SAME_TYPE

FY_SAME_TYPE(_a, _b)
    Test whether two expressions have the same type.

Parameters

•   _a – First expression.

•   _b – Second expression.

  Description

On GCC/Clang uses __builtin_types_compatible_p to compare the types of _a and _b (via __typeof__). On compilers without this builtin always evaluates to true to avoid false negatives.

  Return

Non-zero (true) if the types match, zero (false) otherwise.

  macro FY_CHECK_SAME_TYPE

FY_CHECK_SAME_TYPE(_a, _b)
    Trigger a compile error if two expressions have different types.

Parameters

•   _a – First expression.

•   _b – Second expression.

  Description

Combines FY_SAME_TYPE and FY_COMPILE_ERROR_ON_ZERO. Use in macros that require two operands to have the same type (e.g. overflow-safe arithmetic).

  macro FY_ADD_OVERFLOW

FY_ADD_OVERFLOW(_a, _b, _resp)
    Checked addition: detect signed/unsigned integer overflow.

Parameters

•   _a – First operand.

•   _b – Second operand (must have the same type as _a).

•   _resp – Pointer to receive the result (written even on overflow).

  Description

On GCC/Clang maps directly to __builtin_add_overflow(_a, _b, _resp), which is a single compiler intrinsic with full type generality.

  On other compilers a portable fallback is used that

•   Requires _a and _b to have the same type (enforced at compile time via FY_CHECK_SAME_TYPE).

•   Computes *_resp = _a + _b and returns true if the addition wrapped.

  Return

true if the addition overflowed, false otherwise.

  macro FY_SUB_OVERFLOW

FY_SUB_OVERFLOW(_a, _b, _resp)
    Checked subtraction: detect signed/unsigned integer overflow.

Parameters

•   _a – Minuend.

•   _b – Subtrahend (must have the same type as _a).

•   _resp – Pointer to receive the result (written even on overflow).

  Description

On GCC/Clang maps to __builtin_sub_overflow(_a, _b, _resp). The portable fallback requires _a and _b to have the same type.

  Return

true if the subtraction overflowed, false otherwise.

  macro FY_MUL_OVERFLOW

FY_MUL_OVERFLOW(_a, _b, _resp)
    Checked multiplication: detect signed/unsigned integer overflow.

Parameters

•   _a – First factor.

•   _b – Second factor (must have the same type as _a).

•   _resp – Pointer to receive the result (written even on overflow).

  Description

On GCC/Clang maps to __builtin_mul_overflow(_a, _b, _resp). The portable fallback requires _a and _b to have the same type and detects overflow by dividing the product back and comparing with the original operand.

  Return

true if the multiplication overflowed, false otherwise.

  macro fy_sprintfa

fy_sprintfa(_fmt, ...)
    Format a string into a stack buffer using inline arguments.

Parameters

•   _fmt – printf-style format string.

•   ellipsis (ellipsis) – Format arguments.

  Description

Like fy_vsprintfa() but accepts arguments directly (uses __VA_ARGS__). Two calls to snprintf() are made: the first with a NULL buffer to measure the required length, the second to write the result into a stack-allocated buffer.

The returned pointer is valid only for the lifetime of the enclosing function.

  Return

char * to a NUL-terminated stack buffer.

  macro FY_CPP_EVAL1

FY_CPP_EVAL1(...)
    Force one additional macro-expansion pass.

Parameters

•   ellipsis (ellipsis) – Token sequence to re-expand.

  Description

Expands its argument list once. Use as a building block for deeper evaluation levels; prefer FY_CPP_EVAL() for most uses.

  macro FY_CPP_EVAL2

FY_CPP_EVAL2(...)
    Force two additional macro-expansion passes.

Parameters

•   ellipsis (ellipsis) – Token sequence to re-expand.

  macro FY_CPP_EVAL4

FY_CPP_EVAL4(...)
    Force four additional macro-expansion passes.

Parameters

•   ellipsis (ellipsis) – Token sequence to re-expand.

  macro FY_CPP_EVAL8

FY_CPP_EVAL8(...)
    Force eight additional macro-expansion passes.

Parameters

•   ellipsis (ellipsis) – Token sequence to re-expand.

  macro FY_CPP_EVAL16

FY_CPP_EVAL16(...)
    Force 16 additional macro-expansion passes (GCC only).

Parameters

•   ellipsis (ellipsis) – Token sequence to re-expand.

  Description

Not defined on Clang, which exhausts its expansion buffer before reaching 16 levels. Wrap FY_CPP_MAP() / FY_CPP_MAP2() in FY_CPP_EVAL() instead of calling this directly.

  macro FY_CPP_EVAL

FY_CPP_EVAL(...)
    Force maximum macro-expansion depth.

Parameters

•   ellipsis (ellipsis) – Token sequence to fully expand.

  Description

On GCC performs 32 expansion passes (supports lists up to ~32 elements). On Clang performs 16 passes (supports lists up to ~16 elements).

Always use this (rather than a specific EVALn) unless you have a known bound on the number of arguments.

  macro FY_CPP_EMPTY

FY_CPP_EMPTY(void)
    Produce an empty token sequence (deferred).

Parameters

•   void – no arguments

  Description

Expands to nothing. Used in combination with FY_CPP_POSTPONE1() / FY_CPP_POSTPONE2() to defer macro expansion by one scan pass, breaking the preprocessor’s blue-paint recursion guard.

  macro FY_CPP_POSTPONE1

FY_CPP_POSTPONE1(macro)
    Defer a single-argument macro by one expansion pass.

Parameters

•   macro – Macro token to postpone.

  Description

Expands to the macro name macro followed by a deferred FY_CPP_EMPTY(), so the macro call is not completed until the next pass.

  macro FY_CPP_POSTPONE2

FY_CPP_POSTPONE2(a, macro)
    Defer a two-argument macro by one expansion pass.

Parameters

•   a – Fixed first argument (carried along, not expanded yet).

•   macro – Macro token to postpone.

  Description

Like FY_CPP_POSTPONE1() but for macros that take a leading fixed argument a.

  macro FY_CPP_FIRST

FY_CPP_FIRST(...)
    Extract the first argument from a variadic list.

Parameters

•   ellipsis (ellipsis) – Variadic argument list.

  Description

Returns the first argument, or 0 if the list is empty.

  Return

First argument token, or 0.

  macro FY_CPP_SECOND

FY_CPP_SECOND(...)
    Extract the second argument from a variadic list.

Parameters

•   ellipsis (ellipsis) – Variadic argument list.

  Description

Returns the second argument, or 0 if fewer than two arguments are present.

  Return

Second argument token, or 0.

  macro FY_CPP_THIRD

FY_CPP_THIRD(...)
    Extract the third argument.

Parameters

•   ellipsis (ellipsis) – Variadic argument list. Returns: Third argument, or 0.

  macro FY_CPP_FOURTH

FY_CPP_FOURTH(...)
    Extract the fourth argument.

Parameters

•   ellipsis (ellipsis) – Variadic argument list. Returns: Fourth argument, or 0.

  macro FY_CPP_FIFTH

FY_CPP_FIFTH(...)
    Extract the fifth argument.

Parameters

•   ellipsis (ellipsis) – Variadic argument list. Returns: Fifth argument, or 0.

  macro FY_CPP_SIXTH

FY_CPP_SIXTH(...)
    Extract the sixth argument.

Parameters

•   ellipsis (ellipsis) – Variadic argument list. Returns: Sixth argument, or 0.

  macro FY_CPP_REST

FY_CPP_REST(...)
    Return all arguments after the first.

Parameters

•   ellipsis (ellipsis) – Variadic argument list.

  Description

Expands to the tail of the variadic list with the first element removed. Expands to nothing if the list has zero or one element.

  macro FY_CPP_MAP

FY_CPP_MAP(macro, ...)
    Apply a macro to every argument in a variadic list.

Parameters

•   macro – Single-argument macro to apply.

•   ellipsis (ellipsis) – Arguments to map over.

  Description

Expands macro(x) for each argument x in __VA_ARGS__, concatenating all the results. The argument list must be non-empty. Uses FY_CPP_EVAL() internally, so the list length is bounded by the evaluation depth.

For example:

    #define PRINT_ITEM(x)  printf("%d\n", x);
    FY_CPP_MAP(PRINT_ITEM, 1, 2, 3)
    // expands to: printf("%d\n", 1); printf("%d\n", 2); printf("%d\n", 3);

  macro FY_CPP_VA_COUNT

FY_CPP_VA_COUNT(...)
    Count the number of arguments in a variadic list.

Parameters

•   ellipsis (ellipsis) – Variadic argument list.

  Description

Evaluates to a compile-time integer expression equal to the number of arguments. Returns 0 for an empty list.

  Return

Integer expression giving the argument count.

  macro FY_CPP_VA_ITEMS

FY_CPP_VA_ITEMS(_type, ...)
    Build a compound-literal array from variadic arguments.

Parameters

•   _type – Element type of the resulting array.

•   ellipsis (ellipsis) – Values to place in the array.

  Description

Expands to a compound literal of type _type[N] (where N is the number of arguments) initialised with the provided values. Useful for passing a variadic argument list as an array to a function.

For example:

    // FY_CPP_VA_ITEMS(int, 1, 2, 5, 100)
    // expands to: ((int [4]){ 1, 2, 5, 100 })

  macro FY_CPP_MAP2

FY_CPP_MAP2(a, macro, ...)
    Apply a binary macro to every argument, threading a fixed first argument.

Parameters

•   a – Fixed first argument threaded into every call.

•   macro – Two-argument macro to apply.

•   ellipsis (ellipsis) – Arguments to map over.

  Description

Expands macro(a, x) for each argument x in __VA_ARGS__. The fixed argument a is passed as the first argument to every invocation.

  macro FY_CONCAT

FY_CONCAT(_a, _b)
    Token-paste two arguments after full macro expansion.

Parameters

•   _a – Left token (expanded before pasting).

•   _b – Right token (expanded before pasting).

  Description

Unlike the raw ## operator, this macro forces both _a and _b to be fully expanded before concatenation, so macro arguments are substituted correctly.

  macro FY_UNIQUE

FY_UNIQUE(_base)
    Generate a unique identifier using __COUNTER__.

Parameters

•   _base – Identifier prefix.

  Description

Concatenates _base with the current value of the __COUNTER__ preprocessor counter, which increments by one for each use in a translation unit. Guarantees unique names across multiple macro expansions in the same file.

  macro FY_LUNIQUE

FY_LUNIQUE(_base)
    Generate a unique identifier using __LINE__.

Parameters

•   _base – Identifier prefix.

  Description

Like FY_UNIQUE() but uses the current source line number instead of __COUNTER__. Sufficient when only one such identifier is needed per source line; prefer FY_UNIQUE() in general.

  macro FY_STACK_SAVE

FY_STACK_SAVE(void)
    Save the current stack pointer.

Parameters

•   void – no arguments

  Description

On compilers that provide __builtin_stack_save() (GCC, Clang) returns the current stack pointer as a void *, allowing it to be restored later with FY_STACK_RESTORE(). On other compilers returns (void *)NULL.

Use together with FY_STACK_RESTORE() to bound the stack growth of a loop that calls alloca() on each iteration.

  Return

Opaque stack pointer value, or NULL if unsupported.

  macro FY_STACK_RESTORE

FY_STACK_RESTORE(_x)
    Restore the stack pointer to a previously saved value.

Parameters

•   _x – Value previously returned by FY_STACK_SAVE().

  Description

On compilers that provide __builtin_stack_restore() rewinds the stack pointer to the value captured by FY_STACK_SAVE(). On other compilers this is a no-op that discards _x.

  macro FY_HAVE_LAMBDAS

FY_HAVE_LAMBDAS()
    Defined when the compiler supports anonymous functions.

  Set when either

•   Clang is compiling with -fblocks (Blocks extension) — also sets FY_HAVE_BLOCK_LAMBDAS; or

•   GCC is in use — also sets FY_HAVE_NESTED_FUNC_LAMBDAS (nested functions).

    Code using lambdas should guard against this macro and provide a fallback for environments where it is not defined.

  macro FY_HAVE_BLOCK_LAMBDAS

FY_HAVE_BLOCK_LAMBDAS()
    Defined when Clang Block lambdas are available.

  Description

Set on Clang when compiled with -fblocks. Implies FY_HAVE_LAMBDAS. Block lambdas use the ^(args){ body } syntax.

  macro FY_HAVE_NESTED_FUNC_LAMBDAS

FY_HAVE_NESTED_FUNC_LAMBDAS()
    Defined when GCC nested-function lambdas are available.

  Description

Set on GCC. Implies FY_HAVE_LAMBDAS. Nested function lambdas are defined as local functions inside the enclosing function and cannot outlive it.

  macro FY_DIAG_PUSH

FY_DIAG_PUSH()
    Save the current diagnostic state onto the compiler’s stack.

  Description

Always paired with FY_DIAG_POP.

  macro FY_DIAG_POP

FY_DIAG_POP()
    Restore the diagnostic state saved by the last FY_DIAG_PUSH.

  macro FY_DIAG_IGNORE

FY_DIAG_IGNORE(_warn)
    Suppress a specific warning by pragma string.

Parameters

•   _warn – A string literal suitable for use in a _Pragma() call, e.g. "GCC diagnostic ignored \"-Wsomething\"" .

  macro FY_DIAG_IGNORE_ARRAY_BOUNDS

FY_DIAG_IGNORE_ARRAY_BOUNDS()
    Suppress -Warray-bounds in the current region.

  macro FY_DIAG_IGNORE_UNUSED_VARIABLE

FY_DIAG_IGNORE_UNUSED_VARIABLE()
    Suppress -Wunused-variable in the current region.

  macro FY_DIAG_IGNORE_UNUSED_PARAMETER

FY_DIAG_IGNORE_UNUSED_PARAMETER()
    Suppress -Wunused-parameter in the current region.

  macro FY_FLT_MANT_DIG

FY_FLT_MANT_DIG()
    Number of base-2 mantissa digits in a float.

  Description

Typically 24 (IEEE 754 single precision). Fallback: 9.

  macro FY_DBL_MANT_DIG

FY_DBL_MANT_DIG()
    Number of base-2 mantissa digits in a double.

  Description

Typically 53 (IEEE 754 double precision). Fallback: 17.

  macro FY_LDBL_MANT_DIG

FY_LDBL_MANT_DIG()
    Number of base-2 mantissa digits in a long double.

  Description

Varies by platform (64-bit x87 extended: 64; MSVC/ARM == double: 53). Fallback: 17.

  macro FY_FLT_DECIMAL_DIG

FY_FLT_DECIMAL_DIG()
    Decimal digits required for a round-trip float.

  Description

The minimum number of significant decimal digits such that converting a float to decimal and back recovers the original value exactly. Typically 9. Fallback: 9.

  macro FY_DBL_DECIMAL_DIG

FY_DBL_DECIMAL_DIG()
    Decimal digits required for a round-trip double.

  Description

Typically 17. Fallback: 17.

  macro FY_LDBL_DECIMAL_DIG

FY_LDBL_DECIMAL_DIG()
    Decimal digits required for a round-trip long double.

  Description

Varies by platform; same as double on most non-x87 targets. Fallback: 17.

ALLOCATOR

This header exposes libfyaml’s pluggable allocator subsystem. Rather than using malloc/free directly, the library routes certain internal allocations through a struct fy_allocator. This lets callers trade memory footprint, speed, and deduplication behaviour to match their workload.

Available strategies (select by name when calling fy_allocator_create()):

•   "linear" — bump-pointer arena. Allocation is O(1) and near-zero overhead; individual frees are a no-op. Ideal for parse-and-discard workflows where the entire arena is released at once.

•   "malloc" — thin wrapper around the system malloc/free. Familiar semantics; useful when individual node lifetimes vary. Should never be used for regular application builds. The presence of it is for having a ASAN/valgrind compatible allocator where buffer overflows can be detected easily.

•   "mremap" — growable linear arena backed by mremap(2). Avoids copying when the arena needs to grow. While mremap is Linux specific, this allocator can be configured to use mmap() or malloc() areas where they work for other platforms.

•   "dedup" — content-addressed store built on xxhash hashing. Stores each unique byte sequence exactly once and returns a shared pointer to all callers. Dramatically reduces memory use when parsing documents with many repeated keys or values (e.g. large YAML configurations, test-suite corpora).

•   "auto" — heuristic selection: given a policy. It usually can do the right thing and is a safe bet.

    Tags partition an allocator’s address space. Obtain a tag with fy_allocator_get_tag() and pass it to every fy_allocator_alloc() / fy_allocator_store() call; release the whole tag’s memory in one shot with fy_allocator_release_tag(). This maps naturally to document lifetimes.

    In-place variants (fy_linear_allocator_create_in_place(), fy_dedup_allocator_create_in_place()) initialise the allocator inside a caller-supplied buffer — zero dynamic setup cost, useful in stack-allocated or shared-memory contexts.

  fy_allocator_iterate

const char *fy_allocator_iterate(const char **prevp)
    Iterate over available allocator names

Parameters

•   prevp (const char**) – The previous allocator iterator pointer

  Description

This method iterates over all the available allocator names. The start of the iteration is signalled by a NULL in *prevp.

  Return

The next allocator name in sequence or NULL at the end.

  fy_allocator_is_available

bool fy_allocator_is_available(const char *name)
    Check if an allocator is available

Parameters

•   name (const char*) – The name of the allocator to check

  Description

Check if the named allocator is available.

  Return

true if the allocator is available, false otherwise

  fy_allocator_create

struct fy_allocator *fy_allocator_create(const char *name, const void *cfg)
    Create an allocator.

Parameters

•   name (const char*) – The name of the allocator

•   cfg (const void*) – The type specific configuration for the allocator, or NULL for the default.

  Description

Creates an allocator of the given type, using the configuration argument provided. The allocator may be destroyed by a corresponding call to fy_allocator_destroy().

You can retrieve the names of available allocators with the fy_allocator_get_names() method.

  Return

A pointer to the allocator or NULL in case of an error.

  fy_allocator_destroy

void fy_allocator_destroy(struct fy_allocator *a)
    Destroy the given allocator

Parameters

•   a (struct fy_allocator*) – The allocator to destroy

  Description

Destroy an allocator created earlier via fy_allocator_create(). Tracking allocators will release all memory allocated using them.

  fy_linear_allocator_create_in_place

struct fy_allocator *fy_linear_allocator_create_in_place(void *buffer, size_t size)
    Create a linear allocator in place

Parameters

•   buffer (void*) – The memory buffer to use for both storage and the allocator

•   size (size_t) – The size of the memory buffer

  Description

Creates a linear allocator in place, using the buffer provided. No memory allocations will be performed, so it’s safe to embed. There is no need to call fy_allocator_destroy for this allocator.

  Return

A pointer to the allocator, or NULL if there is no space

  fy_dedup_allocator_create_in_place

struct fy_allocator *fy_dedup_allocator_create_in_place(void *buffer, size_t size)
    Create a dedup allocator in place

Parameters

•   buffer (void*) – The memory buffer to use for both storage and the allocator

•   size (size_t) – The size of the memory buffer

  Description

Creates a dedup allocator in place, using the buffer provided. No memory allocations will be performed, so it’s safe to embed. There is no need to call fy_allocator_destroy for this allocator. The parent allocator of this will be a linear allocator.

  Return

A pointer to the allocator, or NULL if there is no space

  fy_allocator_get_tag

int fy_allocator_get_tag(struct fy_allocator *a)
    Get a tag from an allocator

Parameters

•   a (struct fy_allocator*) – The allocator

  Description

The allocator interface requires all allocation to belong to a tag. This call creates a tag and returns its value, or an error if not available.

If an allocator only provides a single tag (like the linear allocator for instance), the same tag number, usually 0, is returned.

  Return

The created tag or -1 in case of an error.

  fy_allocator_release_tag

void fy_allocator_release_tag(struct fy_allocator *a, int tag)
    Release a tag from an allocator

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag to release

  Description

Releases a tag from an allocator and frees all memory it allocated (if such an operation is provided by the allocator).

  fy_allocator_get_tag_count

int fy_allocator_get_tag_count(struct fy_allocator *a)
    Get the maximum number of tags a allocator supports

Parameters

•   a (struct fy_allocator*) – The allocator

  Description

Get the maximum amount of tags an allocator supports.

If an allocator only provides a single tag (like the linear allocator for instance), 1 will be returned.

  Return

The number of tags, or -1 on error

  fy_allocator_set_tag_count

int fy_allocator_set_tag_count(struct fy_allocator *a, unsigned int count)
    Set the maximum number of tags a allocator supports

Parameters

•   a (struct fy_allocator*) – The allocator

•   count (unsigned int) – The amount of tags the allocator should support

  Description

Sets the maximum amount of tags an allocator supports. If the set allocator tag count is less than the current the additional tags will be released.

  Return

0 on success, -1 on error

  fy_allocator_trim_tag

void fy_allocator_trim_tag(struct fy_allocator *a, int tag)
    Trim a tag

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag to trim

  Description

Trim a tag, that is free any excess memory it allocator, fitting it to the size of the content it carries. Allocators that cannot perform this operation treat it as a NOP.

  fy_allocator_reset_tag

void fy_allocator_reset_tag(struct fy_allocator *a, int tag)
    Reset a tag

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag to reset

  Description

Reset a tag, that is free any content it carries, but do not release the tag.

  fy_allocator_alloc

void *fy_allocator_alloc(struct fy_allocator *a, int tag, size_t size, size_t align)
    Allocate memory from an allocator

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag to allocate from

•   size (size_t) – The size of the memory to allocate

•   align (size_t) – The alignment of the object

  Description

Allocate memory from the given allocator tag, satisfying the size and align restrictions.

  Return

A pointer to the allocated memory or NULL

  fy_allocator_free

void fy_allocator_free(struct fy_allocator *a, int tag, void *ptr)
    Free memory allocated from an allocator

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag used to allocate the memory

•   ptr (void*) – The pointer to the memory to free

  Description

Attempt to free the memory allocated previously by fy_allocator_alloc() Note that non per object tracking allocators treat this as a NOP

  fy_allocator_store

const void *fy_allocator_store(struct fy_allocator *a, int tag, const void *data, size_t size, size_t align)
    Store an object to an allocator

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag used to allocate the memory

•   data (const void*) – The pointer to object to store

•   size (size_t) – The size of the object

•   align (size_t) – The alignment restriction of the object

  Description

Store an object to an allocator and return a pointer to the location it was stored. When using a deduplicating allocator no new allocation will take place and a pointer to the object already stored will be returned.

The return pointer must not be modified, the objects stored are idempotent.

  Return

A constant pointer to the object stored, or NULL in case of an error

  fy_allocator_storev

const void *fy_allocator_storev(struct fy_allocator *a, int tag, const struct iovec *iov, int iovcnt, size_t align)
    Store an object to an allocator (scatter gather)

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag used to allocate the memory from

•   iov (const struct iovec*) – The I/O scatter gather vector

•   iovcnt (int) – The number of vectors

•   align (size_t) – The alignment restriction of the object

  Description

Store an object to an allocator and return a pointer to the location it was stored. When using a deduplicating allocator no new allocation will take place and a pointer to the object already stored will be returned.

The object is created linearly from the scatter gather io vector provided.

The return pointer must not be modified, the objects stored are immutable.

  Return

A constant pointer to the object stored, or NULL in case of an error

  fy_allocator_lookup

const void *fy_allocator_lookup(struct fy_allocator *a, int tag, const void *data, size_t size, size_t align)
    Lookup for object in an allocator.

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag used to locate the memory

•   data (const void*) – The pointer to object to store

•   size (size_t) – The size of the object

•   align (size_t) – The alignment restriction of the object

  Description

Lookup for the exact contents of an object stored in an allocator and return a pointer to the location it was stored. The allocator must have the FYACF_CAN_LOOKUP capability.

  Return

A constant pointer to the object stored, or NULL if the object does not exist

  fy_allocator_lookupv

const void *fy_allocator_lookupv(struct fy_allocator *a, int tag, const struct iovec *iov, int iovcnt, size_t align)
    Lookup for object in an allocator (scatter gather)

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag used to search into

•   iov (const struct iovec*) – The I/O scatter gather vector

•   iovcnt (int) – The number of vectors

•   align (size_t) – The alignment restriction of the object

  Description

Lookup for the exact contents of an object stored in an allocator and return a pointer to the location it was stored. The allocator must have the FYACF_CAN_LOOKUP capability.

The scatter gather vector is used to recreate the object.

  Return

A constant pointer to the object stored, or NULL in case the object does not exist

  fy_allocator_dump

void fy_allocator_dump(struct fy_allocator *a)
    Dump internal allocator state

Parameters

•   a (struct fy_allocator*) – The allocator

  enum fy_allocator_cap_flags

enum fy_allocator_cap_flags
    Allocator capability flags

  Definition

    enum fy_allocator_cap_flags {
        FYACF_CAN_FREE_INDIVIDUAL,
        FYACF_CAN_FREE_TAG,
        FYACF_CAN_DEDUP,
        FYACF_HAS_CONTAINS,
        FYACF_HAS_EFFICIENT_CONTAINS,
        FYACF_HAS_TAGS,
        FYACF_CAN_LOOKUP
    };

  Constants

FYACF_CAN_FREE_INDIVIDUAL
    Allocator supports freeing individual allocations

FYACF_CAN_FREE_TAG
    Allocator supports releasing entire tags

FYACF_CAN_DEDUP
    Allocator supports deduplication

FYACF_HAS_CONTAINS
    Allocator can report if it contains a pointer (even if inefficiently)

FYACF_HAS_EFFICIENT_CONTAINS
    Allocator can report if it contains a pointer (efficiently)

FYACF_HAS_TAGS
    Allocator has individual tags or not

FYACF_CAN_LOOKUP
    Allocator supports lookup for content

  Description

These flags describe what operations an allocator supports.

  fy_allocator_get_caps

enum fy_allocator_cap_flags fy_allocator_get_caps(struct fy_allocator *a)
    Get allocator capabilities

Parameters

•   a (struct fy_allocator*) – The allocator

  Description

Retrieve the capabilities of an allocator.

  Return

The capabilities of the allocator

  fy_allocator_contains

bool fy_allocator_contains(struct fy_allocator *a, int tag, const void *ptr)
    Check if a allocator contains a pointer

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – Tag to search in, -1 for all

•   ptr (const void*) – The object pointer

  Description

Report if an allocator contains the pointer

  Return

true if the pointer ptr is contained in the allocator, false otherwise

  fy_allocator_get_tag_linear_size

ssize_t fy_allocator_get_tag_linear_size(struct fy_allocator *a, int tag)
    Get the linear size of an allocator tag

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag

  Description

Retrieve the linear size of the content of a tag. That is the size of a buffer if one was to copy the content of the tag in that buffer in a linear manner.

  Return

The linear size of the content stored in the tag or -1 in case of an error.

  fy_allocator_get_tag_single_linear

const void *fy_allocator_get_tag_single_linear(struct fy_allocator *a, int tag, size_t *sizep)
    Get the linear extend of a tag

Parameters

•   a (struct fy_allocator*) – The allocator

•   tag (int) – The tag

•   sizep (size_t*) – Pointer to a variable that will be filled with the size.

  Description

If a tag stores it’s content in a single linear buffer, retrieve it directly. This is possible only under careful arrangement of allocator configuration, but it is an important optimization case.

  Return

A pointer to the linear content of the tag, or NULL if othersize.

  struct fy_linear_allocator_cfg

struct fy_linear_allocator_cfg
    linear allocator configuration

  Definition

    struct fy_linear_allocator_cfg {
        void *buf;
        size_t size;
    }

  Members

buf A pointer to a buffer that will be used, or NULL in order to allocate

size
    Size of the buffer in bytes

  enum fy_mremap_arena_type

enum fy_mremap_arena_type
    The mremap allocator arena types

  Definition

    enum fy_mremap_arena_type {
        FYMRAT_DEFAULT,
        FYMRAT_MALLOC,
        FYMRAT_MMAP
    };

  Constants

FYMRAT_DEFAULT
    Use what’s optimal for this platform

FYMRAT_MALLOC
    Use malloc/realloc arena type (not recommended)

FYMRAT_MMAP
    Use mmap/mremap arena type

  struct fy_mremap_allocator_cfg

struct fy_mremap_allocator_cfg
    mremap allocator configuration

  Definition

    struct fy_mremap_allocator_cfg {
        size_t big_alloc_threshold;
        size_t empty_threshold;
        size_t minimum_arena_size;
        float grow_ratio;
        float balloon_ratio;
        enum fy_mremap_arena_type arena_type;
    }

  Members

big_alloc_threshold
    Threshold for immediately creating a new arena.

empty_threshold
    The threshold under which an arena is moved to the full list.

minimum_arena_size
    The minimum (and starting size) of an arena.

grow_ratio
    The ratio which an arena will try to grow if full (>1.0)

balloon_ratio
    The multiplier for the vm area first allocation

arena_type
    The arena type

  Description

If any of the fields is zero, then the system will provide (somewhat) reasonable defaults.

  struct fy_dedup_allocator_cfg

struct fy_dedup_allocator_cfg
    dedup allocator configuration

  Definition

    struct fy_dedup_allocator_cfg {
        struct fy_allocator *parent_allocator;
        unsigned int bloom_filter_bits;
        unsigned int bucket_count_bits;
        size_t dedup_threshold;
        unsigned int chain_length_grow_trigger;
        size_t estimated_content_size;
        float minimum_bucket_occupancy;
    }

  Members

parent_allocator
    The parent allocator (required)

bloom_filter_bits
    Number of bits of the bloom filter (or 0 for default)

bucket_count_bits
    Number of bits for the bucket count (or 0 for default)

dedup_threshold
    Number of bytes over which dedup takes place (default 0=always)

chain_length_grow_trigger
    Chain length of a bucket over which a grow takes place (or 0 for auto)

estimated_content_size
    Estimated content size (or 0 for don’t know)

minimum_bucket_occupancy
    The minimum amount that a tag bucket must be full before growth is allowed (default 50%, or 0.0)

  enum fy_auto_allocator_scenario_type

enum fy_auto_allocator_scenario_type
    auto allocator scenario type

  Definition

    enum fy_auto_allocator_scenario_type {
        FYAST_PER_TAG_FREE,
        FYAST_PER_TAG_FREE_DEDUP,
        FYAST_PER_OBJ_FREE,
        FYAST_PER_OBJ_FREE_DEDUP,
        FYAST_SINGLE_LINEAR_RANGE,
        FYAST_SINGLE_LINEAR_RANGE_DEDUP
    };

  Constants

FYAST_PER_TAG_FREE
    only per tag freeing, no individual obj free

FYAST_PER_TAG_FREE_DEDUP
    per tag freeing, dedup obj store

FYAST_PER_OBJ_FREE
    object freeing allowed, tag freeing still works

FYAST_PER_OBJ_FREE_DEDUP
    per obj freeing, dedup obj store

FYAST_SINGLE_LINEAR_RANGE
    just a single linear range, no frees at all

FYAST_SINGLE_LINEAR_RANGE_DEDUP
    single linear range, with dedup

  struct fy_auto_allocator_cfg

struct fy_auto_allocator_cfg
    auto allocator configuration

  Definition

    struct fy_auto_allocator_cfg {
        enum fy_auto_allocator_scenario_type scenario;
        size_t estimated_max_size;
    }

  Members

scenario
    Auto allocator scenario

estimated_max_size
    Estimated max content size (or 0 for don’t know)

THREADING

This header provides a simple, portable thread pool built on POSIX threads. It is used internally by the BLAKE3 hasher and the generic type system’s parallel map/filter/reduce operations, and is also available as a public API for application use.

Two operational modes are supported:

Work-stealing mode (FYTPCF_STEAL_MODE): the recommended mode for data-parallel loops. Submit a batch of work items with fy_thread_work_join(); the pool distributes items across threads and the caller participates in the execution. About 30% faster than reservation mode for typical workloads.

Reservation mode: explicitly reserve a thread with fy_thread_reserve(), submit a single work item with fy_thread_submit_work(), continue doing other work in the calling thread, then synchronise with fy_thread_wait_work(). Release the thread afterwards with fy_thread_unreserve().

Three convenience wrappers over fy_thread_work_join() cover the most common data-parallel patterns:

•   fy_thread_args_join() — array of heterogeneous argument pointers

•   fy_thread_arg_array_join() — flat array of equal-sized argument items

•   fy_thread_arg_join() — same argument broadcast to N invocations

    An optional fy_work_check_fn callback lets each call site decide at runtime whether a given item is worth offloading to a thread or running inline.

  typedef fy_work_exec_fn

void fy_work_exec_fn(void *arg)
    Work exec function

Parameters

•   arg (void*) – The argument to the method

  Description

The callback executed on work submission

  typedef fy_work_check_fn

bool fy_work_check_fn(const void *arg)
    Work check function

Parameters

•   arg (const void*) – The argument to the method

  Description

Work checker function to decide if it’s worth to offload to a thread.

  Return

true if it should offload to thread, false otherwise

  struct fy_thread_work

struct fy_thread_work
    Work submitted to a thread for execution

  Definition

    struct fy_thread_work {
        fy_work_exec_fn fn;
        void *arg;
        struct fy_work_pool *wp;
    }

  Members

fn  The execution function for this work

arg The argument to the fn

wp  Used internally, must be set to NULL on entry

  Description

This is the structure describing the work submitted to a thread for execution.

  enum fy_thread_pool_cfg_flags

enum fy_thread_pool_cfg_flags
    Thread pool configuration flags

  Definition

    enum fy_thread_pool_cfg_flags {
        FYTPCF_STEAL_MODE
    };

  Constants

FYTPCF_STEAL_MODE
    Enable steal mode for the thread pool

  Description

These flags control the operation of the thread pool. For now only the steal mode flag is defined.

  struct fy_thread_pool_cfg

struct fy_thread_pool_cfg
    thread pool configuration structure.

  Definition

    struct fy_thread_pool_cfg {
        enum fy_thread_pool_cfg_flags flags;
        unsigned int num_threads;
        void *userdata;
    }

  Members

flags
    Thread pool configuration flags

num_threads
    Number of threads, if 0 == online CPUs

userdata
    A userdata pointer

  Description

Argument to the fy_thread_pool_create() method.

  fy_thread_pool_create

struct fy_thread_pool *fy_thread_pool_create(const struct fy_thread_pool_cfg *cfg)
    Create a thread pool

Parameters

•   cfg (const struct fy_thread_pool_cfg*) – The configuration for the thread pool

  Description

Creates a thread pool with its configuration cfg The thread pool may be destroyed by a corresponding call to fy_thread_pool_destroy().

  Return

A pointer to the thread pool or NULL in case of an error.

  fy_thread_pool_destroy

void fy_thread_pool_destroy(struct fy_thread_pool *tp)
    Destroy the given thread pool

Parameters

•   tp (struct fy_thread_pool*) – The thread pool to destroy

  Description

Destroy a thread pool created earlier via fy_thread_pool_create(). Note that this function will block until all threads of the pool are destroyed.

  fy_thread_pool_get_num_threads

int fy_thread_pool_get_num_threads(struct fy_thread_pool *tp)
    Get the number of threads

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

  Description

Returns the actual number of created threads.

  Return

> 0 for the number of actual threads created, -1 on error

  fy_thread_pool_get_cfg

const struct fy_thread_pool_cfg *fy_thread_pool_get_cfg(struct fy_thread_pool *tp)
    Get the configuration of a thread pool

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

  Return

The configuration of the thread pool

  fy_thread_reserve

struct fy_thread *fy_thread_reserve(struct fy_thread_pool *tp)
    Reserve a thread from the pool.

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

  Description

Reserve a thread from the pool and return it. Note this is only valid for a non-work stealing thread pool. You release the thread again via a call to fy_thread_unreserve.

  Return

A reserved thread if not NULL, NULL if no threads are available.

  fy_thread_unreserve

void fy_thread_unreserve(struct fy_thread *t)
    Unreserve a previously reserved thread

Parameters

•   t (struct fy_thread*) – The thread

  Description

Unreserve a thread previously reserved via a call to fy_thread_reserve() Note this is only valid for a non-work stealing thread pool.

  fy_thread_submit_work

int fy_thread_submit_work(struct fy_thread *t, struct fy_thread_work *work)
    Submit work for execution

Parameters

•   t (struct fy_thread*) – The thread

•   work (struct fy_thread_work*) – The work

  Description

Submit work for execution. If successful the thread will start executing the work in parallel with the calling thread. You can wait for the thread to terminate via a call to fy_thread_wait_work(). The thread must have been reserved earlier via fy_thread_reserve()

Note this is only valid for a non-work stealing thread pool.

  Return

0 if work has been submitted, -1 otherwise.

  fy_thread_wait_work

int fy_thread_wait_work(struct fy_thread *t)
    Wait for completion of submitted work

Parameters

•   t (struct fy_thread*) – The thread

  Description

Wait until submitted work to the thread has finished. Note this is only valid for a non-work stealing thread pool.

  Return

0 if work finished, -1 on error.

  fy_thread_pool_are_all_reserved

bool fy_thread_pool_are_all_reserved(struct fy_thread_pool *tp)
    Check whether no threads are free

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

  Return

true if all threads are currently reserved, false otherwise.

  fy_thread_pool_is_any_reserved

bool fy_thread_pool_is_any_reserved(struct fy_thread_pool *tp)
    Check whether at least one thread is reserved

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

  Return

true if any thread is currently reserved, false otherwise.

  fy_thread_work_join

void fy_thread_work_join(struct fy_thread_pool *tp, struct fy_thread_work *works, size_t work_count, fy_work_check_fn check_fn)
    Submit works for execution and wait

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

•   works (struct fy_thread_work*) – Pointer to an array of works sized work_count

•   work_count (size_t) – The size of the works array

•   check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

  Description

Submit works for possible parallel execution. If no offloading is possible at the time execute in the current context. It is possible to use in both stealing and non-stealing mode with the difference being that stealing mode is about 30% faster.

  fy_thread_args_join

void fy_thread_args_join(struct fy_thread_pool *tp, fy_work_exec_fn fn, fy_work_check_fn check_fn, void **args, size_t count)
    Execute function in parallel using arguments as pointers

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

•   fn (fy_work_exec_fn) – The function to execute in parallel

•   check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

•   args (void**) – An args array sized count of argument pointers

•   count (size_t) – The count of the args array items

  Description

Execute fn possibly in parallel using the threads in the thread pool. The arguments of the function are provided by the args array.

  fy_thread_arg_array_join

void fy_thread_arg_array_join(struct fy_thread_pool *tp, fy_work_exec_fn fn, fy_work_check_fn check_fn, void *args, size_t argsize, size_t count)
    Execute function in parallel using argument array

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

•   fn (fy_work_exec_fn) – The function to execute in parallel

•   check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

•   args (void*) – An args array of argsize items

•   argsize (size_t) – The size of each argument array item

•   count (size_t) – The count of the args array items

  Description

Execute fn possibly in parallel using the threads in the thread pool. The arguments of the function are provided by the args array.

  fy_thread_arg_join

void fy_thread_arg_join(struct fy_thread_pool *tp, fy_work_exec_fn fn, fy_work_check_fn check_fn, void *arg, size_t count)
    Execute function in parallel with the same argument

Parameters

•   tp (struct fy_thread_pool*) – The thread pool

•   fn (fy_work_exec_fn) – The function to execute in parallel

•   check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

•   arg (void*) – The common argument

•   count (size_t) – The count of executions

  Description

Execute fn possibly in parallel using the threads in the thread pool. The argument of the functions is the same.

BLAKE3 HASHING

This header exposes libfyaml’s embedded BLAKE3 hasher. BLAKE3 is a modern, highly parallelisable cryptographic hash function producing 256-bit (32-byte) output.

Three hashing modes are supported, selected via struct fy_blake3_hasher_cfg at creation time:

•   Standard: plain BLAKE3 hash (default when key and context are NULL)

•   Keyed: MAC-like hash using a 32-byte key

•   Key derivation: derive a subkey from an application context string

    The hasher can be used in streaming fashion (update / finalize) or for one-shot hashing of memory regions (fy_blake3_hash()) and files (fy_blake3_hash_file()). File hashing uses mmap by default for large files and can be further parallelised via a thread pool.

    Runtime SIMD backend selection is automatic: the best available backend (SSE2, SSE4.1, AVX2, AVX512 on x86; NEON on ARM; portable C otherwise) is used unless a specific backend name is requested in the config. Use fy_blake3_backend_iterate() to enumerate available backends.

    The hasher object is reusable: call fy_blake3_hasher_reset() to start a new hash without reallocating the object.

  fy_blake3_backend_iterate

const char *fy_blake3_backend_iterate(const char **prevp)
    Iterate over the supported BLAKE3 backends

Parameters

•   prevp (const char**) – The previous backend pointer, or NULL at start

  Description

This method iterates over the supported BLAKE3 backends. The start of the iteration is signalled by a NULL in *prevp.

The default backend is always the last in sequence, so for example if the order is [ “portable”, “sse2”, NULL ] the default is “sse2”.

  Return

The next backend or NULL at the end.

  struct fy_blake3_hasher_cfg

struct fy_blake3_hasher_cfg
    BLAKE3 hasher configuration

  Definition

    struct fy_blake3_hasher_cfg {
        const char *backend;
        size_t file_buffer;
        size_t mmap_min_chunk;
        size_t mmap_max_chunk;
        bool no_mmap;
        const uint8_t *key;
        const void *context;
        size_t context_len;
        struct fy_thread_pool *tp;
        int num_threads;
    }

  Members

backend
    NULL for default, or a specific backend name

file_buffer
    Use this amount of buffer for buffering, zero for default

mmap_min_chunk
    Minimum chunk size for mmap case

mmap_max_chunk
    Maximum chunk size for mmap case

no_mmap
    Disable mmap for file access

key pointer to a FY_BLAKE3_KEY_LEN area when in keyed mode. NULL otherwise.

context
    pointer to a context when in key derivation mode. NULL otherwise.

context_len
    The size of the context when in key derivation mode. 0 otherwise.

tp  The thread pool to use, if NULL, create a private one

num_threads
    Number of threads to use - 0 means default: NUM_CPUS * 3 / 2 - > 0 specific number of threads - -1 disable threading entirely

  Description

Argument to the fy_blake3_hasher_create() method which is the fyaml’s user facing BLAKE3 API. It is very minimal, on purpose, since it’s meant to be exposing a full blown BLAKE3 API.

  fy_blake3_hasher_create

struct fy_blake3_hasher *fy_blake3_hasher_create(const struct fy_blake3_hasher_cfg *cfg)
    Create a BLAKE3 hasher object.

Parameters

•   cfg (const struct fy_blake3_hasher_cfg*) – The configuration for the BLAKE3 hasher

  Description

Creates a BLAKE3 hasher with its configuration cfg The hasher may be destroyed by a corresponding call to fy_blake3_hasher_destroy().

  Return

A pointer to the BLAKE3 hasher or NULL in case of an error.

  fy_blake3_hasher_destroy

void fy_blake3_hasher_destroy(struct fy_blake3_hasher *fyh)
    Destroy the given BLAKE3 hasher

Parameters

•   fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher to destroy

  Description

Destroy a BLAKE3 hasher created earlier via fy_blake3_hasher_create().

  fy_blake3_hasher_update

void fy_blake3_hasher_update(struct fy_blake3_hasher *fyh, const void *input, size_t input_len)
    Update the BLAKE3 hasher state with the given input

Parameters

•   fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

•   input (const void*) – Pointer to the input

•   input_len (size_t) – Size of the input in bytes

  Description

Updates the BLAKE3 hasher state by hashing the given input.

  fy_blake3_hasher_finalize

const uint8_t *fy_blake3_hasher_finalize(struct fy_blake3_hasher *fyh)
    Finalize the hash and get output

Parameters

•   fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

  Description

Finalizes the BLAKE3 hasher and returns the output

  Return

A pointer to the BLAKE3 output (sized FY_BLAKE3_OUT_LEN), or NULL in case of an error.

  fy_blake3_hasher_reset

void fy_blake3_hasher_reset(struct fy_blake3_hasher *fyh)
    Resets the hasher

Parameters

•   fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

  Description

Resets the hasher for re-use

  fy_blake3_hash

const uint8_t *fy_blake3_hash(struct fy_blake3_hasher *fyh, const void *mem, size_t size)
    BLAKE3 hash a memory area

Parameters

•   fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

•   mem (const void*) – Pointer to the memory to use

•   size (size_t) – The size of the memory in bytes

  Description

Hash a memory area and return the BLAKE3 output.

  Return

A pointer to the BLAKE3 output (sized FY_BLAKE3_OUT_LEN), or NULL in case of an error.

  fy_blake3_hash_file

const uint8_t *fy_blake3_hash_file(struct fy_blake3_hasher *fyh, const char *filename)
    BLAKE3 hash a file.

Parameters

•   fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

•   filename (const char*) – The filename

  Description

Hash the given file (possibly using mmap)

  Return

A pointer to the BLAKE3 output (sized FY_BLAKE3_OUT_LEN), or NULL in case of an error.

ALIGNMENT

This header provides portable utilities for working with memory alignment requirements, from compile-time attributes to runtime allocation and pointer-rounding helpers. It has no libfyaml dependencies.

Compile-time attributes

•   FY_ALIGNED_TO(x) — apply an alignment attribute to a variable or type; expands to __attribute__((aligned(x))) on GCC/Clang and __declspec(align(x)) on MSVC

•   FY_CACHELINE_ALIGN — shorthand for cache-line (64-byte) alignment, useful for preventing false sharing between fields accessed concurrently by different threads

    Value rounding

•   FY_ALIGN(align, x) — round an integer up to the next multiple of align (must be a power of two)

•   FY_CACHELINE_SIZE_ALIGN(x) — round up to the next cache-line boundary

•   fy_ptr_align(p, align) — round a pointer up to alignment

•   fy_size_t_align(sz, align) — round a size_t value up to alignment

    Heap allocation

•   fy_align_alloc(align, size) / fy_align_free(p) — allocate and free memory with an explicit alignment (posix_memalign on POSIX, _aligned_malloc on Windows)

•   fy_cacheline_alloc(size) / fy_cacheline_free(p) — convenience wrappers that fix the alignment at FY_CACHELINE_SIZE

    Stack allocation

•   fy_alloca_align(sz, align) — allocate a block on the stack with a specified alignment; uses plain alloca when alignment fits within max_align_t, otherwise over-allocates and advances the pointer

  macro FY_ALIGNED_TO

FY_ALIGNED_TO(x)
    Declare that a variable or type has a minimum alignment.

Parameters

•   x – Required alignment in bytes (must be a power of two).

  Description

Expands to the appropriate compiler-specific alignment attribute: - GCC/Clang: __attribute__((aligned(x))) - MSVC: should be __declspec(align(x)) but MSVC does not support trailing alignment… - Other: empty (no enforced alignment)

  macro FY_ALIGN

FY_ALIGN(_align, _x)
    Round _x up to the next multiple of _align.

Parameters

•   _align – Alignment boundary (power of two).

•   _x – Value to round up.

  Description

_align must be a power of two. The result is always >= _x and is the smallest multiple of _align that is >= _x.

  Return

_x rounded up to the nearest multiple of _align.

  macro FY_CACHELINE_SIZE

FY_CACHELINE_SIZE()
    Size of a CPU cache line in bytes.

  Description

Universally 64 bytes on all currently supported architectures (x86, x86_64, ARM, ARM64, PowerPC).

  macro FY_CACHELINE_SIZE_ALIGN

FY_CACHELINE_SIZE_ALIGN(_x)
    Round _x up to the next cache-line boundary.

Parameters

•   _x – Value to round up.

  Return

_x rounded up to the nearest multiple of FY_CACHELINE_SIZE.

  macro FY_CACHELINE_ALIGN

FY_CACHELINE_ALIGN()
    Alignment attribute for cache-line-aligned objects.

  Description

Apply to a variable or struct field to ensure it starts on a cache-line boundary, preventing false sharing between concurrent readers/writers.

Example:

    struct my_data {
        FY_CACHELINE_ALIGN int hot_counter;
        int cold_field;
    };

  fy_align_alloc

void *fy_align_alloc(size_t align, size_t size)
    Allocate memory with a specific alignment.

Parameters

•   align (size_t) – Required alignment in bytes (must be a power of two and >= sizeof(void *) ).

•   size (size_t) – Number of bytes to allocate.

  Description

Allocates size bytes rounded up to the nearest multiple of align, with the returned pointer guaranteed to be a multiple of align.

Uses posix_memalign() on POSIX systems and _aligned_malloc() on Windows. Free the result with fy_align_free().

  Return

Pointer to the allocated block, or NULL on failure.

  fy_align_free

void fy_align_free(void *p)
    Free memory allocated by fy_align_alloc().

Parameters

•   p (void*) – Pointer previously returned by fy_align_alloc(), or NULL.

  Description

A NULL p is silently ignored.

  fy_cacheline_alloc

void *fy_cacheline_alloc(size_t size)
    Allocate cache-line-aligned memory.

Parameters

•   size (size_t) – Number of bytes to allocate.

  Description

Equivalent to fy_align_alloc(FY_CACHELINE_SIZE, size). Free the result with fy_cacheline_free().

  Return

Cache-line-aligned pointer, or NULL on failure.

  fy_cacheline_free

void fy_cacheline_free(void *p)
    Free memory allocated by fy_cacheline_alloc().

Parameters

•   p (void*) – Pointer previously returned by fy_cacheline_alloc(), or NULL.

  Description

A NULL p is silently ignored.

  fy_ptr_align

void *fy_ptr_align(void *p, size_t align)
    Round a pointer up to the next multiple of align.

Parameters

•   p (void*) – Pointer to align.

•   align (size_t) – Alignment boundary in bytes (must be a power of two).

  Description

Does not allocate any memory; the caller is responsible for ensuring the underlying buffer extends at least (@align - 1) bytes past p.

  Return

p rounded up to the nearest multiple of align.

  fy_size_t_align

size_t fy_size_t_align(size_t size, size_t align)
    Round a size_t value up to the next multiple of align.

Parameters

•   size (size_t) – Value to round up.

•   align (size_t) – Alignment boundary in bytes (must be a power of two).

  Return

size rounded up to the nearest multiple of align.

  macro fy_alloca_align

fy_alloca_align(_sz, _align)
    Stack-allocate a buffer with a specific alignment.

Parameters

•   _sz – Number of bytes to allocate.

•   _align – Required alignment in bytes (must be a power of two).

  Description

Expands to a statement expression (GCC extension) that allocates _sz bytes on the stack, aligned to _align bytes. When _align <= sizeof(max_align_t) a plain alloca() is used; otherwise _sz + _align - 1 bytes are allocated and the pointer is advanced with fy_ptr_align(). This macro does not work on MSVC.

The result is valid only for the lifetime of the enclosing function; do not return or store it beyond that scope.

  Return

Stack pointer aligned to _align.

ENDIANNESS

This header provides a portable way to include the platform’s byte-order detection headers and ensures the following macros are always defined:

•   __BYTE_ORDER — the byte order of the current platform

•   __BIG_ENDIAN — big-endian sentinel value

•   __LITTLE_ENDIAN — little-endian sentinel value

    Usage:

        #include <libfyaml/fy-internal-endian.h>
        #if __BYTE_ORDER == __LITTLE_ENDIAN
            // little-endian path
        #else
            // big-endian path
        #endif

    Supported platforms: - Linux / Cygwin / OpenBSD / GNU Hurd / Emscripten — via <endian.h> - macOS / iOS — via <libkern/OSByteOrder.h> + <machine/endian.h> - NetBSD / FreeBSD / DragonFly BSD — via <sys/endian.h> - Windows (MSVC) — via <winsock2.h> (+ <sys/param.h> for MinGW)

    The non-standard BYTE_ORDER, BIG_ENDIAN, and LITTLE_ENDIAN spellings are aliased to the double-underscore variants if needed.

  macro bswap_8

bswap_8(x)
    Byte-swap an 8-bit value (no-op).

Parameters

•   x – The 8-bit value.

  Description

Defined for symmetry with bswap_16(), bswap_32(), and bswap_64(). Swapping a single byte is always a no-op.

  Return

x unchanged.

VARIABLE-LENGTH SIZE ENCODING

Encodes unsigned integer sizes into a compact, self-delimiting byte stream. The encoding is modelled after the variable-length quantity (VLQ / LEB128 big-endian variant) used in MIDI and other binary formats:

•   Each byte carries 7 bits of payload in bits 6..0.

•   Bit 7 (MSB) is a continuation flag: 1 means more bytes follow, 0 means this is the last byte.

•   Exception: the final (maximum-length) byte is always 8 bits of payload with no continuation bit, allowing the full 64-bit / 32-bit range.

    64-bit encoding (up to 9 bytes):

        bytes   bits   value range
        1       7      0 .. 127
        2       14     128 .. 16383
        3       21     16384 .. 2097151
        4       28     2097152 .. 268435455
        5       35     268435456 .. 34359738367
        6       42     ..
        7       49     ..
        8       56     ..
        9       64     full uint64_t range

    32-bit encoding (up to 5 bytes):

        bytes   bits   value range
        1       7      0 .. 127
        2       14     128 .. 16383
        3       21     16384 .. 2097151
        4       28     2097152 .. 268435455
        5       32     full uint32_t range (top 4 bits of byte 0 ignored)

    The native-width fy_encode_size() / fy_decode_size() family selects the 64-bit or 32-bit variant based on SIZE_MAX.

    Each family provides four operations:

•   _bytes() — compute the encoded length without writing anything

•   encode() — write the encoding into a bounded buffer

•   decode() — read and validate from a bounded buffer

•   decode_nocheck() — read without bounds checking (caller guarantees room)

•   skip() — advance past an encoded value in a bounded buffer

•   skip_nocheck() — advance without bounds checking

  macro FYVL_SIZE_ENCODING_MAX_64

FYVL_SIZE_ENCODING_MAX_64()
    Maximum encoded length of a 64-bit size value.

  Description

A 64-bit value requires at most 9 bytes: 8 x 7-bit groups plus one final unconstrained byte = 7 x 8 + 8 = 64 bits.

  macro FYVL_SIZE_ENCODING_MAX_32

FYVL_SIZE_ENCODING_MAX_32()
    Maximum encoded length of a 32-bit size value.

  Description

A 32-bit value requires at most 5 bytes: 4 x 7-bit groups plus one final unconstrained byte = 7 x 4 + 4 = 32 bits.

  fy_encode_size32_bytes

unsigned int fy_encode_size32_bytes(uint32_t size)
    Compute the encoded byte count for a 32-bit size.

Parameters

•   size (uint32_t) – The value whose encoded length is queried.

  Description

Returns the number of bytes that fy_encode_size32() would write for size, without actually writing anything. Useful for pre-allocating buffers.

  Return

Number of bytes required (1–5).

  fy_encode_size32

uint8_t *fy_encode_size32(uint8_t *p, uint32_t bufsz, uint32_t size)
    Encode a 32-bit size into a buffer.

Parameters

•   p (uint8_t*) – Start of the output buffer.

•   bufsz (uint32_t) – Available space in bytes.

•   size (uint32_t) – Value to encode.

  Description

Writes the variable-length encoding of size into the buffer [@p, p+@bufsz).

  Return

Pointer to one past the last written byte, or NULL if bufsz was
    too small.

  fy_decode_size32

const uint8_t *fy_decode_size32(const uint8_t *start, size_t bufsz, uint32_t *sizep)
    Decode a variable-length 32-bit size from a buffer.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   bufsz (size_t) – Available bytes to read.

•   sizep (uint32_t*) – Output: the decoded value. Set to (uint32_t)-1 on error.

  Description

Reads bytes from [@start, start+@bufsz) and reconstructs the encoded 32-bit value. Stops after FYVL_SIZE_ENCODING_MAX_32 bytes at most.

  Return

Pointer to one past the last consumed byte, or NULL if the buffer
    was exhausted before a complete value was found.

  fy_decode_size32_nocheck

const uint8_t *fy_decode_size32_nocheck(const uint8_t *start, uint64_t *sizep)
    Decode a 32-bit size without bounds checking.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   sizep (uint64_t*) – Output: the decoded value as a uint64_t for uniform handling.

  Description

Like fy_decode_size32() but assumes the buffer is large enough to hold a complete encoding. The caller must guarantee at least FYVL_SIZE_ENCODING_MAX_32 bytes are available at start.

  Return

Pointer to one past the last consumed byte.

  fy_skip_size32

const uint8_t *fy_skip_size32(const uint8_t *start, size_t bufsz)
    Skip past a variable-length 32-bit size in a buffer.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   bufsz (size_t) – Available bytes.

  Description

Advances past the encoded value without decoding it. Useful when the value itself is not needed.

  Return

Pointer to one past the last consumed byte, or NULL if the buffer
    was exhausted before a complete encoding was found.

  fy_skip_size32_nocheck

const uint8_t *fy_skip_size32_nocheck(const uint8_t *p)
    Skip a 32-bit encoded size without bounds checking.

Parameters

•   p (const uint8_t*) – Start of the encoded data.

  Description

Like fy_skip_size32() but assumes the buffer is large enough. The caller must guarantee at least FYVL_SIZE_ENCODING_MAX_32 bytes are readable.

  Return

Pointer to one past the last consumed byte.

  fy_encode_size64_bytes

unsigned int fy_encode_size64_bytes(uint64_t size)
    Compute the encoded byte count for a 64-bit size.

Parameters

•   size (uint64_t) – The value whose encoded length is queried.

  Description

Returns the number of bytes that fy_encode_size64() would write for size, without writing anything.

  Return

Number of bytes required (1–9).

  fy_encode_size64

uint8_t *fy_encode_size64(uint8_t *p, size_t bufsz, uint64_t size)
    Encode a 64-bit size into a buffer.

Parameters

•   p (uint8_t*) – Start of the output buffer.

•   bufsz (size_t) – Available space in bytes.

•   size (uint64_t) – Value to encode.

  Description

Writes the variable-length encoding of size into the buffer [@p, p+@bufsz).

  Return

Pointer to one past the last written byte, or NULL if bufsz was
    too small.

  fy_decode_size64

const uint8_t *fy_decode_size64(const uint8_t *start, size_t bufsz, uint64_t *sizep)
    Decode a variable-length 64-bit size from a buffer.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   bufsz (size_t) – Available bytes to read.

•   sizep (uint64_t*) – Output: the decoded value. Set to (size_t)-1 on error.

  Description

Reads bytes from [@start, start+@bufsz) and reconstructs the encoded 64-bit value. Stops after FYVL_SIZE_ENCODING_MAX_64 bytes at most.

  Return

Pointer to one past the last consumed byte, or NULL if the buffer
    was exhausted before a complete value was found.

  fy_decode_size64_nocheck

const uint8_t *fy_decode_size64_nocheck(const uint8_t *start, uint64_t *sizep)
    Decode a 64-bit size without bounds checking.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   sizep (uint64_t*) – Output: the decoded value.

  Description

Like fy_decode_size64() but assumes the buffer is large enough. The caller must guarantee at least FYVL_SIZE_ENCODING_MAX_64 bytes are readable.

  Return

Pointer to one past the last consumed byte.

  fy_skip_size64

const uint8_t *fy_skip_size64(const uint8_t *start, size_t bufsz)
    Skip past a variable-length 64-bit size in a buffer.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   bufsz (size_t) – Available bytes.

  Description

Advances past the encoded value without decoding it.

  Return

Pointer to one past the last consumed byte, or NULL if the buffer
    was exhausted before a complete encoding was found.

  fy_skip_size64_nocheck

const uint8_t *fy_skip_size64_nocheck(const uint8_t *p)
    Skip a 64-bit encoded size without bounds checking.

Parameters

•   p (const uint8_t*) – Start of the encoded data.

  Description

Like fy_skip_size64() but assumes the buffer is large enough. The caller must guarantee at least FYVL_SIZE_ENCODING_MAX_64 bytes are readable.

  Return

Pointer to one past the last consumed byte.

  fy_encode_size_bytes

unsigned int fy_encode_size_bytes(size_t size)
    Compute encoded byte count for a native size_t.

Parameters

•   size (size_t) – The value whose encoded length is queried.

  Description

Selects fy_encode_size64_bytes() or fy_encode_size32_bytes() based on SIZE_MAX.

  Return

Number of bytes required.

  fy_encode_size

uint8_t *fy_encode_size(uint8_t *p, size_t bufsz, size_t size)
    Encode a native size_t into a buffer.

Parameters

•   p (uint8_t*) – Start of the output buffer.

•   bufsz (size_t) – Available space in bytes.

•   size (size_t) – Value to encode.

  Description

Selects fy_encode_size64() or fy_encode_size32() based on SIZE_MAX.

  Return

Pointer to one past the last written byte, or NULL on overflow.

  fy_decode_size

const uint8_t *fy_decode_size(const uint8_t *start, size_t bufsz, size_t *sizep)
    Decode a native size_t from a buffer.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   bufsz (size_t) – Available bytes.

•   sizep (size_t*) – Output: the decoded value.

  Description

Selects fy_decode_size64() or fy_decode_size32() based on SIZE_MAX.

  Return

Pointer to one past the last consumed byte, or NULL on error.

  fy_decode_size_nocheck

const uint8_t *fy_decode_size_nocheck(const uint8_t *start, size_t *sizep)
    Decode a native size_t without bounds checking.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   sizep (size_t*) – Output: the decoded value.

  Description

Selects the 64-bit or 32-bit nocheck variant based on sizeof(size_t). The caller must guarantee enough bytes are available at start.

  Return

Pointer to one past the last consumed byte.

  fy_skip_size

const uint8_t *fy_skip_size(const uint8_t *start, size_t bufsz)
    Skip a native size_t encoding in a buffer.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

•   bufsz (size_t) – Available bytes.

  Description

Selects fy_skip_size64() or fy_skip_size32() based on SIZE_MAX.

  Return

Pointer to one past the last consumed byte, or NULL on error.

  fy_skip_size_nocheck

const uint8_t *fy_skip_size_nocheck(const uint8_t *start)
    Skip a native size_t encoding without bounds checking.

Parameters

•   start (const uint8_t*) – Start of the encoded data.

  Description

Selects the 64-bit or 32-bit nocheck variant based on SIZE_MAX. The caller must guarantee enough bytes are available.

  Return

Pointer to one past the last consumed byte.

  macro FYVL_SIZE_ENCODING_MAX

FYVL_SIZE_ENCODING_MAX()
    Maximum encoded length for a native size_t.

  Description

Equals FYVL_SIZE_ENCODING_MAX_64 on 64-bit platforms, FYVL_SIZE_ENCODING_MAX_32 on 32-bit platforms.

ATOMIC OPERATIONS

This header provides a thin, portable abstraction over C11 <stdatomic.h> with graceful fallback for compilers that support _Atomic as an extension (GCC without -std=c11, Clang) and a last-resort non-atomic fallback for toolchains that support neither.

Detection macros (defined by this header, not meant for direct use):

•

FY_HAVE_STDATOMIC_H — <stdatomic.h> was successfully included;
    the standard atomic_* functions and types are available.

•

FY_HAVE_C11_ATOMICS — the _Atomic qualifier is available, either
    from <stdatomic.h> or as a compiler extension.

•

FY_HAVE_ATOMICS — effective atomics are available (_Atomic
    maps to a real atomic type). When not defined, _Atomic(_x) expands to plain _x and all operations are non-atomic single-threaded stubs.

•

FY_HAVE_SAFE_ATOMIC_OPS — the underlying operations are properly
    memory-ordered (i.e. <stdatomic.h> is in use). Without this, operations are performed as plain loads/stores with no memory barriers.

    Public API — all fy_atomic_* macros delegate to the selected backend:

•   FY_ATOMIC() — qualify a type as atomic

•   fy_atomic_flag — boolean flag type

•   fy_atomic_load() / fy_atomic_store()

•   fy_atomic_exchange()

•   fy_atomic_compare_exchange_strong() / fy_atomic_compare_exchange_weak()

•   fy_atomic_fetch_add() / fy_atomic_fetch_sub()

•   fy_atomic_fetch_or() / fy_atomic_fetch_xor() / fy_atomic_fetch_and()

•   fy_atomic_flag_clear() / fy_atomic_flag_set() / fy_atomic_flag_test_and_set()

•   fy_cpu_relax() — emit a CPU relaxation hint (PAUSE/YIELD)

•   fy_atomic_get_and_clear_counter() — atomically read and subtract a counter

  macro FY_ATOMIC

FY_ATOMIC(_x)
    Qualify a type as atomic.

Parameters

•   _x – The underlying C type.

  Description

Expands to _Atomic(_x) when FY_HAVE_ATOMICS is defined, or to plain _x otherwise (non-atomic fallback).

Example:

    FY_ATOMIC(uint64_t) refcount;

  macro fy_atomic_flag

fy_atomic_flag()
    A boolean flag that can be set/cleared/tested atomically.

  Description

Backed by atomic_flag from <stdatomic.h> when available, or a plain bool in the fallback path.

  macro fy_atomic_load

fy_atomic_load(_ptr)
    Atomically load the value at _ptr.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified variable.

  Return

The current value.

  macro fy_atomic_store

fy_atomic_store(_ptr, _v)
    Atomically store _v at _ptr.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified variable.

•   _v – Value to store.

  macro fy_atomic_exchange

fy_atomic_exchange(_ptr, _v)
    Atomically replace the value at _ptr with _v.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified variable.

•   _v – New value to store.

  Return

The old value that was at _ptr before the exchange.

  macro fy_atomic_compare_exchange_strong

fy_atomic_compare_exchange_strong(_ptr, _e, _d)
    Strong CAS: replace _ptr‘s value if it equals _e.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified variable.

•   _e – Pointer to the expected value (updated on failure).

•   _d – Desired value to store on success.

  Description

If *_ptr == *_e, stores _d into _ptr and returns true. Otherwise, loads the current value into _e and returns false. The strong variant never spuriously fails.

  Return

true if the exchange succeeded, false otherwise.

  macro fy_atomic_compare_exchange_weak

fy_atomic_compare_exchange_weak(_ptr, _e, _d)
    Weak CAS: may spuriously fail.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified variable.

•   _e – Pointer to the expected value (updated on failure).

•   _d – Desired value to store on success.

  Description

Like fy_atomic_compare_exchange_strong() but may fail even when *_ptr == *_e. Prefer in retry loops where a spurious failure is harmless and performance matters.

  Return

true if the exchange succeeded, false otherwise.

  macro fy_atomic_fetch_add

fy_atomic_fetch_add(_ptr, _v)
    Atomically add _v to _ptr and return the old value.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified integer variable.

•   _v – Value to add.

  Return

The value of _ptr before the addition.

  macro fy_atomic_fetch_sub

fy_atomic_fetch_sub(_ptr, _v)
    Atomically subtract _v from _ptr and return the old value.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified integer variable.

•   _v – Value to subtract.

  Return

The value of _ptr before the subtraction.

  macro fy_atomic_fetch_or

fy_atomic_fetch_or(_ptr, _v)
    Atomically OR _v into _ptr and return the old value.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified integer variable.

•   _v – Value to OR in.

  Return

The value of _ptr before the operation.

  macro fy_atomic_fetch_xor

fy_atomic_fetch_xor(_ptr, _v)
    Atomically XOR _v into _ptr and return the old value.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified integer variable.

•   _v – Value to XOR in.

  Return

The value of _ptr before the operation.

  macro fy_atomic_fetch_and

fy_atomic_fetch_and(_ptr, _v)
    Atomically AND _v into _ptr and return the old value.

Parameters

•   _ptr – Pointer to an FY_ATOMIC-qualified integer variable.

•   _v – Value to AND in.

  Return

The value of _ptr before the operation.

  macro fy_atomic_flag_clear

fy_atomic_flag_clear(_ptr)
    Atomically clear a flag (set to false).

Parameters

•   _ptr – Pointer to an fy_atomic_flag.

  macro fy_atomic_flag_set

fy_atomic_flag_set(_ptr)
    Atomically set a flag (set to true).

Parameters

•   _ptr – Pointer to an fy_atomic_flag.

  Note

this is a libfyaml extension; standard <stdatomic.h> only provides atomic_flag_test_and_set(). In the fallback path this is implemented as a plain store.

  macro fy_atomic_flag_test_and_set

fy_atomic_flag_test_and_set(_ptr)
    Atomically set a flag and return its old value.

Parameters

•   _ptr – Pointer to an fy_atomic_flag.

  Description

Sets the flag to true and returns the value it held before the operation. This is the standard test-and-set primitive.

  Return

true if the flag was already set, false if it was clear.

  fy_cpu_relax

void fy_cpu_relax(void)
    Emit a CPU relaxation hint inside a spin-wait loop.

Parameters

•   void – no arguments

  Description

Reduces power consumption and improves hyper-threading performance on x86/x86_64 (PAUSE), signals a yield on AArch64/ARM (YIELD), and emits a low-priority hint on PowerPC (or 27,27,27). Falls back to a compiler memory barrier on unsupported architectures.

Use inside tight spin loops to avoid memory-ordering penalties and allow sibling hardware threads to make progress:

    while (!fy_atomic_load(&ready))
        fy_cpu_relax();

COPYRIGHT
2019-2026, Pantelis Antoniou