view release on metacpan or  search on metacpan

infix/include/infix/infix.h  view on Meta::CPAN

    size_t size;                  /**< The size of the type in bytes. */
    size_t alignment;             /**< The alignment requirement of the type in bytes. */
    bool is_arena_allocated;      /**< True if this type object lives in an arena and must be freed with it. */
    bool is_incomplete;           /**< True if this is a forward declaration that has not yet been defined. */
    infix_arena_t * arena;        /**< A pointer to the arena that owns this type object, or nullptr if static. */
    size_t source_offset;         /**< The byte offset in the source signature where this type was defined. */
    /** @brief A union containing metadata specific to the type's category. */
    union {
        /** @brief Metadata for `INFIX_TYPE_PRIMITIVE`. */
        infix_primitive_type_id primitive_id;
        /** @brief Metadata for `INFIX_TYPE_POINTER`. */
        struct {
            struct infix_type_t * pointee_type; /**< The type that this pointer points to. */
        } pointer_info;
        /** @brief Metadata for `INFIX_TYPE_STRUCT` and `INFIX_TYPE_UNION`. */
        struct {
            infix_struct_member * members; /**< An array of the aggregate's members. */
            size_t num_members;            /**< The number of members in the array. */
            bool is_packed;                /**< True if the struct is packed (!{...}). */
        } aggregate_info;
        /** @brief Metadata for `INFIX_TYPE_ARRAY`. */
        struct {
            struct infix_type_t * element_type; /**< The type of each element in the array. */
            size_t num_elements;                /**< The number of elements in the array. */
            bool is_flexible;                   /**< Indicates this is a flexible array member */
        } array_info;
        /** @brief Metadata for `INFIX_TYPE_REVERSE_TRAMPOLINE`. */
        struct {
            struct infix_type_t * return_type; /**< The return type of the function. */
            infix_function_argument * args;    /**< An array of the function's arguments. */
            size_t num_args;                   /**< The total number of arguments. */
            size_t num_fixed_args;             /**< The number of non-variadic arguments. */
        } func_ptr_info;
        /** @brief Metadata for `INFIX_TYPE_ENUM`. */
        struct {
            struct infix_type_t * underlying_type; /**< The underlying integer type of the enum. */
        } enum_info;
        /** @brief Metadata for `INFIX_TYPE_COMPLEX`. */
        struct {
            struct infix_type_t * base_type; /**< The base floating-point type (`float` or `double`). */
        } complex_info;
        /** @brief Metadata for `INFIX_TYPE_VECTOR`. */
        struct {
            struct infix_type_t * element_type; /**< The primitive type of each element in the vector. */
            size_t num_elements;                /**< The number of elements in the vector. */
        } vector_info;
        /** @brief Metadata for `INFIX_TYPE_NAMED_REFERENCE`. */
        struct {
            const char * name;                             /**< The name to be looked up in a registry. */
            infix_aggregate_category_t aggregate_category; /**< The expected kind of aggregate (struct or union). */
        } named_reference;
    } meta;
};
/**
 * @struct infix_struct_member_t
 * @brief Describes a single member of a C struct or union.
 */
struct infix_struct_member_t {
    const char * name; /**< The name of the member, or `nullptr` if anonymous. */
    infix_type * type; /**< The `infix_type` of the member. */
    size_t offset; /**< The byte offset of the member from the start of the aggregate. For bitfields, the offset of the
                      storage unit that contains them. */
    uint8_t bit_width;  /**< The width of the bitfield in bits. 0 for standard members. */
    uint8_t bit_offset; /**< For bitfields, the bit offset of the field within its storage unit (0-63); 0 for standard
                           members. */
    bool is_bitfield;   /**< True if this member is a bitfield (even if width is 0). */
};
/**
 * @struct infix_function_argument_t
 * @brief Describes a single argument to a C function.
 */
struct infix_function_argument_t {
    const char * name; /**< The name of the argument, or `nullptr` if anonymous. */
    infix_type * type; /**< The `infix_type` of the argument. */
};
/** @} */  // end of type_system group
/**
 * @defgroup memory_management Memory Management
 * @brief APIs for memory management, including custom allocators and arenas.
 * @{
 */
/**
 * @typedef infix_allocator_t
 * @brief A v-table of allocation callbacks used for all of infix's internal heap allocations.
 * @details infix routes every internal heap allocation through these four callbacks.
 *          By default they point to the C library's `malloc`, `calloc`, `realloc`, and
 *          `free`. Replace them at runtime with `infix_set_allocator()` to make infix
 *          allocate from your own memory manager (e.g. a language runtime's tracked
 *          heap or a garbage collector).
 *
 *          The callbacks must honor the usual C library semantics: `malloc(0)` and
 *          `calloc(0, n)` may return `NULL` or a unique pointer, `realloc` must accept
 *          a `NULL` pointer (acting like `malloc`), and `free` must accept `NULL` as a
 *          no-op. Memory returned by one callback must be released with the matching
 *          `free` callback. Never mix allocators.
 */
typedef struct {
    void * (*malloc)(size_t);          /**< Equivalent of `malloc`. */
    void * (*calloc)(size_t, size_t);  /**< Equivalent of `calloc`. */
    void * (*realloc)(void *, size_t); /**< Equivalent of `realloc`. */
    void (*free)(void *);              /**< Equivalent of `free`. */
} infix_allocator_t;
/**
 * @brief The allocator currently used for all of infix's internal heap allocations.
 * @details Initialized to the C library's `malloc`/`calloc`/`realloc`/`free`. Do not
 *          assign to it directly. Use `infix_set_allocator()` so the documentation
 *          and any future locking stay in one place.
 */
extern infix_allocator_t infix_allocator;
/**
 * @brief Replaces the allocator infix uses for all internal heap allocations.
 * @param[in] allocator A pointer to a valid `infix_allocator_t`, or `NULL` to restore
 *            the default C library allocator.
 * @details infix copies the callback pointers, so the caller may pass a temporary
 *          struct. Call this before creating any trampolines (typically during host
 *          initialization) and before infix is used from more than one thread, since
 *          the table is not internally synchronized.
 *
 *          Every pointer infix returns must be freed through the same allocator:
 *          callers that release infix-owned memory (such as the buffer returned by
 *          `emit_get_binary`) must use `infix_free` or the equivalent entry point