Direct Marshalling API

An advanced, high-performance API for language bindings. More...

Collaboration diagram for Direct Marshalling API:

Classes
union	infix_direct_value_t
	A union to hold any primitive value returned by a scalar marshaller. More...
struct	infix_direct_arg_handler_t
	A struct containing all the necessary handlers for a single function argument. More...

Typedefs
typedef void(*	infix_direct_cif_func) (void *, void **)
	A function pointer for a direct marshalling forward trampoline.
typedef infix_direct_value_t(*	infix_marshaller_fn) (void *source_object)
	A function pointer for a custom marshaller for scalar types.
typedef void(*	infix_aggregate_marshaller_fn) (void *source_object, void *dest_buffer, const infix_type *type)
	A function pointer for a custom marshaller for aggregate types (structs/unions).
typedef void(*	infix_writeback_fn) (void *source_object, void *c_data_ptr, const infix_type *type)
	A function pointer for a "write-back" handler for out/in-out parameters.

Functions
c23_nodiscard infix_status	infix_forward_create_direct (infix_forward_t **out_trampoline, const char *signature, void *target_function, infix_direct_arg_handler_t *handlers, infix_registry_t *registry)
	Creates a forward trampoline with direct, JIT-bound marshalling.
c23_nodiscard infix_direct_cif_func	infix_forward_get_direct_code (infix_forward_t *trampoline)
	Gets the callable function pointer from a direct marshalling trampoline.

Detailed Description

An advanced, high-performance API for language bindings.

This API provides a way to create highly optimized forward trampolines that bypass the standard void** argument array. Instead, the JIT-compiled code directly calls user-provided "marshaller" functions to convert language-specific objects into native C arguments just-in-time. This reduces memory indirection and copying, yielding significant performance gains for FFI calls in tight loops.

Typedef Documentation

infix_aggregate_marshaller_fn

typedef void(* infix_aggregate_marshaller_fn) (void *source_object, void *dest_buffer, const infix_type *type)

A function pointer for a custom marshaller for aggregate types (structs/unions).

A language binding provides a function of this type to populate a C struct/union from a language object (e.g., a hash or dictionary).

Parameters

source_object	A void* pointer to the language's native object.
dest_buffer	A pointer to a block of memory, allocated by the JIT trampoline, that is the exact size of the C aggregate. The function must fill this buffer with the native C data.
type	A pointer to the infix_type object describing the C aggregate. The marshaller can introspect this type to determine field names, offsets, and member types.

infix_direct_cif_func

typedef void(* infix_direct_cif_func) (void *, void **)

A function pointer for a direct marshalling forward trampoline.

This is the callable code generated by infix_forward_create_direct. It takes an array of void* pointers that point directly to the language-specific objects (e.g., SV* in Perl, PyObject* in Python).

Parameters

return_value_ptr	A pointer to a buffer to receive the C function's return value.
lang_objects_array	An array of void* pointers to the original language objects.

infix_marshaller_fn

typedef infix_direct_value_t(* infix_marshaller_fn) (void *source_object)

A function pointer for a custom marshaller for scalar types.

A language binding provides a function of this type to convert a language object into a native C primitive value (integer, float, pointer, etc.).

Parameters

source_object

A generic void* pointer to the language's native object.

Returns

An infix_direct_value_t union containing the converted C value.

infix_writeback_fn

typedef void(* infix_writeback_fn) (void *source_object, void *c_data_ptr, const infix_type *type)

A function pointer for a "write-back" handler for out/in-out parameters.

This function is called by the JIT trampoline after the native C function has returned. Its purpose is to update the original language object with any changes made to the C data by the function.

Parameters

source_object	A void* pointer to the original language object that was passed in.
c_data_ptr	A pointer to the (potentially modified) C data buffer that was passed to the C function.
type	A pointer to the infix_type object describing the C data.

Function Documentation

infix_forward_create_direct()

c23_nodiscard infix_status infix_forward_create_direct	(	infix_forward_t **	out_trampoline,
		const char *	signature,
		void *	target_function,
		infix_direct_arg_handler_t *	handlers,
		infix_registry_t *	registry
	)

Creates a forward trampoline with direct, JIT-bound marshalling.

This advanced function generates a highly optimized trampoline that calls user-provided marshaller functions directly from the JIT-compiled code to convert language-specific objects into native C arguments. This avoids intermediate copying and provides the highest performance for forward calls.

Parameters

[out]	out_trampoline	Receives the created trampoline handle upon success.
[in]	signature	The C signature of the target function (e.g., "(int, *char)->void").
[in]	target_function	The address of the C function to be called.
[in]	handlers	An array of infix_direct_arg_handler_t structs, one for each argument of the C function. The array must have exactly as many elements as the function has arguments.
[in]	registry	An optional type registry for resolving named types (@Name) used within the signature. Can be nullptr.

Returns

INFIX_SUCCESS on success, or an error code on failure.

infix_forward_get_direct_code()

c23_nodiscard infix_direct_cif_func infix_forward_get_direct_code

(

infix_forward_t *

trampoline

)

Gets the callable function pointer from a direct marshalling trampoline.

Parameters

[in]

trampoline

The infix_forward_t handle created with infix_forward_create_direct.

Returns

A callable infix_direct_cif_func pointer on success, or nullptr if the trampoline is nullptr or is not a direct marshalling trampoline.