|
infix
A JIT-Powered FFI Library for C
|
The primary, recommended API for creating trampolines from human-readable strings. More...
Modules | |
| Type System | |
| The core data structures and APIs for describing C types and function signatures. | |
| Memory Management | |
| APIs for memory management, including custom allocators and arenas. | |
| Named Type Registry | |
| APIs for defining, storing, and reusing complex types by name. | |
| Registry Introspection API | |
| APIs for inspecting and serializing the contents of a named type registry. | |
| Dynamic Library & Globals API | |
| Cross-platform functions for loading shared libraries and accessing exported symbols. | |
| Manual API | |
A lower-level, programmatic API for creating trampolines from infix_type objects. | |
| Introspection API | |
Functions for inspecting the properties of trampolines and infix_type objects at runtime. | |
| Error Handling API | |
| Functions and types for detailed, thread-safe error reporting. | |
Typedefs | |
| typedef void(* | infix_unbound_cif_func) (void *, void *, void **) |
| A function pointer type for an unbound forward trampoline. | |
| typedef void(* | infix_cif_func) (void *, void **) |
| A function pointer type for a bound forward trampoline. | |
| typedef void(* | infix_closure_handler_fn) (infix_context_t *, void *, void **) |
| A function pointer type for a generic closure handler. | |
Enumerations | |
| enum | infix_status { INFIX_SUCCESS = 0 , INFIX_ERROR_ALLOCATION_FAILED , INFIX_ERROR_INVALID_ARGUMENT , INFIX_ERROR_UNSUPPORTED_ABI , INFIX_ERROR_LAYOUT_FAILED , INFIX_ERROR_PROTECTION_FAILED , INFIX_ERROR_ } |
Enumerates the possible status codes returned by infix API functions. More... | |
Functions | |
| c23_nodiscard infix_status | infix_forward_create (infix_forward_t **, const char *, void *, infix_registry_t *) |
| Creates a "bound" forward trampoline from a signature string. | |
| c23_nodiscard infix_status | infix_forward_create_unbound (infix_forward_t **, const char *, infix_registry_t *) |
| Creates an "unbound" forward trampoline from a signature string. | |
| c23_nodiscard infix_status | infix_forward_create_in_arena (infix_forward_t **, infix_arena_t *, const char *, void *, infix_registry_t *) |
| Creates a "bound" forward trampoline within a user-provided arena. | |
| c23_nodiscard infix_status | infix_reverse_create_callback (infix_reverse_t **, const char *, void *, infix_registry_t *) |
| Creates a type-safe reverse trampoline (callback). | |
| c23_nodiscard infix_status | infix_reverse_create_closure (infix_reverse_t **, const char *, infix_closure_handler_fn, void *, infix_registry_t *) |
| Creates a generic reverse trampoline (closure) for stateful callbacks. | |
| c23_nodiscard infix_status | infix_signature_parse (const char *, infix_arena_t **, infix_type **, infix_function_argument **, size_t *, size_t *, infix_registry_t *) |
| Parses a full function signature string into its constituent parts. | |
| c23_nodiscard infix_status | infix_type_from_signature (infix_type **, infix_arena_t **, const char *, infix_registry_t *) |
| Parses a signature string representing a single data type. | |
The primary, recommended API for creating trampolines from human-readable strings.
This API provides the simplest and most powerful way to interact with infix. All functions in this group take a signature string and an optional type registry to parse and generate the required FFI trampolines.
| typedef void(* infix_cif_func) (void *, void **) |
A function pointer type for a bound forward trampoline.
This is the callable code generated by infix_forward_create. The target C function is "bound" into the JIT-compiled code, offering higher performance.
| return_value_ptr | A pointer to a buffer to receive the return value. Can be nullptr for void returns. |
| args_array | An array of pointers, where each element points to an argument's value. |
| typedef void(* infix_closure_handler_fn) (infix_context_t *, void *, void **) |
A function pointer type for a generic closure handler.
This handler is used with infix_reverse_create_closure and is ideal for language bindings or stateful callbacks where the handler needs access to user-provided data.
| context | The reverse trampoline context, from which user_data can be retrieved via infix_reverse_get_user_data. |
| return_value_ptr | A pointer to a buffer where the handler must write the function's return value. |
| args_array | An array of pointers to the argument values passed by the native C caller. |
| typedef void(* infix_unbound_cif_func) (void *, void *, void **) |
A function pointer type for an unbound forward trampoline.
This is the callable code generated by infix_forward_create_unbound. It takes the target function as its first argument, allowing it to be reused for any C function that matches the signature it was created with.
| target_function | The native C function to call. |
| return_value_ptr | A pointer to a buffer to receive the return value. Can be nullptr if the return type is void. |
| args_array | An array of pointers, where each element points to an argument's value. |
| enum infix_status |
Enumerates the possible status codes returned by infix API functions.
| c23_nodiscard infix_status infix_forward_create | ( | infix_forward_t ** | out_trampoline, |
| const char * | signature, | ||
| void * | target_function, | ||
| infix_registry_t * | registry | ||
| ) |
Creates a "bound" forward trampoline from a signature string.
A bound trampoline is a highly optimized JIT-compiled function where the target C function's address is compiled directly into the executable code. This provides the best performance for forward calls, as it involves a direct call instruction to a known address. It is ideal for situations where you will call the same C function repeatedly.
The returned handle contains a callable function pointer of type infix_cif_func, which you can retrieve with infix_forward_get_code.
| [out] | out_trampoline | A pointer to an infix_forward_t* that will receive the created trampoline handle upon success. |
| [in] | signature | The signature string of the target function (e.g., "(int, int)->int"). |
| [in] | target_function | The address of the C function to be called. |
| [in] | registry | An optional type registry for resolving named types (@Name) used within the signature. Can be nullptr if no named types are used. |
INFIX_SUCCESS on success, or an INFIX_ERROR_... code on failure. infix_forward_destroy.| c23_nodiscard infix_status infix_forward_create_in_arena | ( | infix_forward_t ** | out_trampoline, |
| infix_arena_t * | target_arena, | ||
| const char * | signature, | ||
| void * | target_function, | ||
| infix_registry_t * | registry | ||
| ) |
Creates a "bound" forward trampoline within a user-provided arena.
When the target_arena is the same as the registry's arena, this function will share pointers to named types instead of deep-copying them, saving memory.
| [out] | out_trampoline | Receives the created trampoline handle. |
| [in] | target_arena | The arena to use for the trampoline's internal metadata. |
| [in] | signature | The signature string of the target function. |
| [in] | target_function | The address of the C function to be called. |
| [in] | registry | An optional type registry. |
INFIX_SUCCESS on success. | c23_nodiscard infix_status infix_forward_create_unbound | ( | infix_forward_t ** | out_trampoline, |
| const char * | signature, | ||
| infix_registry_t * | registry | ||
| ) |
Creates an "unbound" forward trampoline from a signature string.
An unbound trampoline is more flexible than a bound one. The target function address is not compiled in; instead, it is provided as the first argument at call time. This is useful for calling multiple C functions that share the same signature without needing to generate a separate trampoline for each one.
The returned handle contains a callable function pointer of type infix_unbound_cif_func, which you can retrieve with infix_forward_get_unbound_code.
| [out] | out_trampoline | A pointer to an infix_forward_t* that will receive the created trampoline handle upon success. |
| [in] | signature | The signature string of the target function. |
| [in] | registry | An optional type registry for resolving named types. Can be nullptr. |
INFIX_SUCCESS on success. infix_forward_destroy.| c23_nodiscard infix_status infix_reverse_create_callback | ( | infix_reverse_t ** | out_context, |
| const char * | signature, | ||
| void * | user_callback_fn, | ||
| infix_registry_t * | registry | ||
| ) |
Creates a type-safe reverse trampoline (callback).
This function generates a native C function pointer that, when called by external C code, will invoke your user_callback_fn. This API is designed primarily for C/C++ developers, as the provided handler function must have a clean, type-safe C signature that exactly matches the one described in the signature string. This provides a high level of convenience and compile-time safety.
| [out] | out_context | A pointer to an infix_reverse_t* that will receive the created context handle. |
| [in] | signature | The signature of the function pointer to be created (e.g., "(int, int)->int"). |
| [in] | user_callback_fn | A pointer to a C function with a matching signature to handle the call. |
| [in] | registry | An optional type registry. |
INFIX_SUCCESS on success. infix_reverse_destroy.| c23_nodiscard infix_status infix_reverse_create_closure | ( | infix_reverse_t ** | out_context, |
| const char * | signature, | ||
| infix_closure_handler_fn | user_callback_fn, | ||
| void * | user_data, | ||
| infix_registry_t * | registry | ||
| ) |
Creates a generic reverse trampoline (closure) for stateful callbacks.
This is the low-level API for reverse calls, designed for language bindings and advanced use cases. The handler function has a generic signature (infix_closure_handler_fn) and receives arguments as a void** array. A user_data pointer can be provided to maintain state between calls, making it a "closure".
This is the most flexible way to handle callbacks, as it allows the handler to be implemented in another language and to access state associated with the callback object.
| [out] | out_context | A pointer to an infix_reverse_t* that will receive the created context handle. |
| [in] | signature | The signature of the function pointer to be created. |
| [in] | user_callback_fn | A pointer to a generic infix_closure_handler_fn. |
| [in] | user_data | A void* pointer to application-specific state. This pointer can be retrieved inside the handler via infix_reverse_get_user_data(context). |
| [in] | registry | An optional type registry. |
INFIX_SUCCESS on success. infix_reverse_destroy.| c23_nodiscard infix_status infix_signature_parse | ( | const char * | signature, |
| infix_arena_t ** | out_arena, | ||
| infix_type ** | out_ret_type, | ||
| infix_function_argument ** | out_args, | ||
| size_t * | out_num_args, | ||
| size_t * | out_num_fixed_args, | ||
| infix_registry_t * | registry | ||
| ) |
Parses a full function signature string into its constituent parts.
This function provides a way to deconstruct a signature string into its components (return_type, arg_types, etc.) without generating a trampoline. It is useful for introspection and for preparing arguments for the Manual API.
| [in] | signature | The signature string to parse. |
| [out] | out_arena | On success, receives a pointer to an arena holding all parsed types. The caller owns this and must free it with infix_arena_destroy. |
| [out] | out_ret_type | On success, receives a pointer to the return type. |
| [out] | out_args | On success, receives a pointer to the array of infix_function_argument structs. |
| [out] | out_num_args | On success, receives the total number of arguments. |
| [out] | out_num_fixed_args | On success, receives the number of fixed (non-variadic) arguments. |
| [in] | registry | An optional type registry. |
INFIX_SUCCESS on success.Like infix_type_from_signature, this function orchestrates the full "Parse -> Estimate -> Copy -> Resolve -> Layout" pipeline, but for a function signature. It unpacks the final, resolved components for the caller.
| [in] | signature | The signature string to parse. |
| [out] | out_arena | On success, receives a pointer to an arena holding all parsed types. The caller owns this and must free it with infix_arena_destroy. |
| [out] | out_ret_type | On success, receives a pointer to the return type. |
| [out] | out_args | On success, receives a pointer to the array of infix_function_argument structs. |
| [out] | out_num_args | On success, receives the total number of arguments. |
| [out] | out_num_fixed_args | On success, receives the number of fixed (non-variadic) arguments. |
| [in] | registry | An optional type registry. |
INFIX_SUCCESS on success. | c23_nodiscard infix_status infix_type_from_signature | ( | infix_type ** | out_type, |
| infix_arena_t ** | out_arena, | ||
| const char * | signature, | ||
| infix_registry_t * | registry | ||
| ) |
Parses a signature string representing a single data type.
This is the core function for introspection, allowing you to get a detailed, fully resolved memory layout for any C type described by a signature.
| [out] | out_type | On success, receives a pointer to the parsed type object. |
| [out] | out_arena | On success, receives a pointer to the arena holding the type. The caller must free this with infix_arena_destroy. |
| [in] | signature | The signature string of the data type (e.g., "{id:int, name:*char}"). |
| [in] | registry | An optional type registry for resolving named types. |
INFIX_SUCCESS on success.This function orchestrates the full **"Parse -> Estimate -> Copy -> Resolve -> Layout"** pipeline for a single type, resulting in a fully resolved and laid-out infix_type object graph.
| [out] | out_type | On success, receives a pointer to the parsed type object. |
| [out] | out_arena | On success, receives a pointer to the arena holding the type. The caller is responsible for freeing this with infix_arena_destroy. |
| [in] | signature | The signature string of the data type (e.g., "{id:int, name:*char}"). |
| [in] | registry | An optional type registry for resolving named types. Can be nullptr. |
INFIX_SUCCESS on success. | infix_aggregate_category_t { ... } ::aggregate_category |
The expected kind of aggregate (struct or union).
| infix_aggregate_category_t infix_type_t::aggregate_category |
The expected kind of aggregate (struct or union).
| struct { ... } infix_type_t::aggregate_info |
Metadata for INFIX_TYPE_STRUCT and INFIX_TYPE_UNION.
| struct { ... } infix_type_t::aggregate_info |
Metadata for INFIX_TYPE_STRUCT and INFIX_TYPE_UNION.
| size_t infix_type_t::alignment |
The alignment requirement of the type in bytes.
| infix_arena_t* infix_type_t::arena |
A pointer to the arena that owns this type object, or nullptr if static.
| infix_function_argument* { ... } ::args |
An array of the function's arguments.
| infix_function_argument* infix_type_t::args |
An array of the function's arguments.
| struct { ... } infix_type_t::array_info |
Metadata for INFIX_TYPE_ARRAY.
| struct { ... } infix_type_t::array_info |
Metadata for INFIX_TYPE_ARRAY.
| struct infix_type_t* { ... } ::base_type |
The base floating-point type (float or double).
| struct infix_type_t* infix_type_t::base_type |
The base floating-point type (float or double).
| infix_type_category infix_type_t::category |
The fundamental category of the type.
| infix_error_category_t infix_error_details_t::category |
The general category of the error.
| infix_error_code_t infix_error_details_t::code |
The specific error code.
| struct { ... } infix_type_t::complex_info |
Metadata for INFIX_TYPE_COMPLEX.
| struct { ... } infix_type_t::complex_info |
Metadata for INFIX_TYPE_COMPLEX.
| struct infix_type_t* infix_type_t::element_type |
The type of each element in the array.
The primitive type of each element in the vector.
| struct infix_type_t* { ... } ::element_type |
The type of each element in the array.
| struct infix_type_t* { ... } ::element_type |
The primitive type of each element in the vector.
| struct { ... } infix_type_t::enum_info |
Metadata for INFIX_TYPE_ENUM.
| struct { ... } infix_type_t::enum_info |
Metadata for INFIX_TYPE_ENUM.
| struct { ... } infix_type_t::func_ptr_info |
Metadata for INFIX_TYPE_REVERSE_TRAMPOLINE.
| struct { ... } infix_type_t::func_ptr_info |
Metadata for INFIX_TYPE_REVERSE_TRAMPOLINE.
| bool infix_type_t::is_arena_allocated |
True if this type object lives in an arena and must be freed with it.
| infix_struct_member* infix_type_t::members |
An array of the aggregate's members.
| infix_struct_member* { ... } ::members |
An array of the aggregate's members.
| char infix_error_details_t::message[256] |
A human-readable description of the error. For parser errors, this includes a code snippet.
| union { ... } infix_type_t::meta |
A union containing metadata specific to the type's category.
The semantic alias of the type (e.g., "MyInt"), or nullptr if anonymous.
The name to be looked up in a registry.
| const char* { ... } ::name |
The name to be looked up in a registry.
| const char* infix_struct_member_t::name |
The name of the member, or nullptr if anonymous.
| const char* infix_function_argument_t::name |
The name of the argument, or nullptr if anonymous.
| struct { ... } infix_type_t::named_reference |
Metadata for INFIX_TYPE_NAMED_REFERENCE.
| struct { ... } infix_type_t::named_reference |
Metadata for INFIX_TYPE_NAMED_REFERENCE.
| size_t { ... } ::num_args |
The total number of arguments.
| size_t infix_type_t::num_args |
The total number of arguments.
| size_t infix_type_t::num_elements |
The number of elements in the array.
The number of elements in the vector.
| size_t { ... } ::num_elements |
The number of elements in the array.
| size_t { ... } ::num_elements |
The number of elements in the vector.
| size_t infix_type_t::num_fixed_args |
The number of non-variadic arguments.
| size_t { ... } ::num_fixed_args |
The number of non-variadic arguments.
| size_t infix_type_t::num_members |
The number of members in the array.
| size_t { ... } ::num_members |
The number of members in the array.
| size_t infix_struct_member_t::offset |
The byte offset of the member from the start of the aggregate.
| struct infix_type_t* infix_type_t::pointee_type |
The type that this pointer points to.
| struct infix_type_t* { ... } ::pointee_type |
The type that this pointer points to.
| struct { ... } infix_type_t::pointer_info |
Metadata for INFIX_TYPE_POINTER.
| struct { ... } infix_type_t::pointer_info |
Metadata for INFIX_TYPE_POINTER.
| size_t infix_error_details_t::position |
For parser errors, the byte offset into the signature string.
| infix_primitive_type_id { ... } ::primitive_id |
Metadata for INFIX_TYPE_PRIMITIVE.
| infix_primitive_type_id infix_type_t::primitive_id |
Metadata for INFIX_TYPE_PRIMITIVE.
| struct infix_type_t* infix_type_t::return_type |
The return type of the function.
| struct infix_type_t* { ... } ::return_type |
The return type of the function.
| size_t infix_type_t::size |
The size of the type in bytes.
| long infix_error_details_t::system_error_code |
The OS-specific error code (e.g., from GetLastError() or errno).
| infix_type* infix_struct_member_t::type |
The infix_type of the member.
| infix_type* infix_function_argument_t::type |
The infix_type of the argument.
| struct infix_type_t* infix_type_t::underlying_type |
The underlying integer type of the enum.
| struct infix_type_t* { ... } ::underlying_type |
The underlying integer type of the enum.
| struct { ... } infix_type_t::vector_info |
Metadata for INFIX_TYPE_VECTOR.
| struct { ... } infix_type_t::vector_info |
Metadata for INFIX_TYPE_VECTOR.