Recommended functions for creating trampolines from a signature string. More...

Collaboration diagram for High-Level Signature API:

Functions
c23_nodiscard infix_status	infix_forward_create (infix_forward_t *, const char , void , infix_registry_t )
	Generates a bound forward-call trampoline from a signature string.

c23_nodiscard infix_status	infix_forward_create_unbound (infix_forward_t *, const char , infix_registry_t *)
	Generates an unbound forward-call trampoline from a signature string.

c23_nodiscard infix_status	infix_reverse_create_callback (infix_reverse_t *, const char , void , infix_registry_t )
	Generates a type-safe reverse-call trampoline (callback) from a signature string.

c23_nodiscard infix_status	infix_reverse_create_closure (infix_reverse_t *, const char , infix_closure_handler_fn, void , infix_registry_t )
	Generates a low-level reverse-call trampoline (closure) from a signature string.

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 infix_type 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.

Detailed Description

Recommended functions for creating trampolines from a signature string.

Function Documentation

◆ infix_forward_create()

c23_nodiscard infix_status infix_forward_create	(	infix_forward_t **	out_trampoline,
		const char *	signature,
		void *	target_function,
		infix_registry_t *	registry
	)

Generates a bound forward-call trampoline from a signature string.

This is the primary and recommended function for creating forward trampolines. It creates a trampoline where the target function address is hardcoded into the JIT-compiled code. This can offer a small performance improvement and a simpler call signature.

Parameters

[out]	out_trampoline	On success, will point to the handle for the new trampoline.
	signature	A null-terminated string describing the function signature.
	target_function	A pointer to the native C function to be bound to the trampoline.
	registry	An optional handle to a type registry for resolving named types. Pass `nullptr` if not used.

Returns: INFIX_SUCCESS on success.

Note: The function pointer returned by infix_forward_get_code should be used.

Generates a bound forward-call trampoline from a signature string.

◆ infix_forward_create_unbound()

c23_nodiscard infix_status infix_forward_create_unbound	(	infix_forward_t **	out_trampoline,
		const char *	signature,
		infix_registry_t *	registry
	)

Generates an unbound forward-call trampoline from a signature string.

Creates a flexible trampoline where the target function is not known at creation time and must be provided at each call. This is useful for interpreters or plugin systems where one trampoline may be used to call multiple functions of the same type.

Parameters

[out]	out_trampoline	On success, will point to the handle for the new trampoline.
	signature	A null-terminated string describing the function signature.
	registry	An optional handle to a type registry for resolving named types. Pass `nullptr` if not used.

Returns: INFIX_SUCCESS on success.

Note: The function pointer returned by infix_forward_get_unbound_code must be used.

Generates an unbound forward-call trampoline from a signature string.

◆ infix_reverse_create_callback()

c23_nodiscard infix_status infix_reverse_create_callback	(	infix_reverse_t **	out_context,
		const char *	signature,
		void *	user_callback_fn,
		infix_registry_t *	registry
	)

Generates a type-safe reverse-call trampoline (callback) from a signature string.

This function parses a signature string to create a native, C-callable function pointer that invokes the provided user handler. This is the recommended API for C/C++ developers as it provides compile-time type safety for the handler.

Parameters

[out]	out_context	On success, will point to the new reverse trampoline context.
	signature	A null-terminated string describing the callback's signature.
	user_callback_fn	A function pointer to the user's C callback handler. Its signature must be a "clean" C signature, exactly matching the types described in the signature string.

Example:: If the native C signature is int (*my_callback)(int, int);, your infix handler function must be int my_handler(int a, int b);.

Parameters

registry An optional handle to a type registry for resolving named types. Pass nullptr if not used.

Returns: INFIX_SUCCESS on success.

Note: This type of callback is stateless. For stateful callbacks, use infix_reverse_create_closure.

Generates a type-safe reverse-call trampoline (callback) from a signature string.

◆ infix_reverse_create_closure()

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
	)

Generates a low-level reverse-call trampoline (closure) from a signature string.

Creates a native C function pointer that invokes a generic handler. This is the recommended API for language binding authors and for creating stateful callbacks.

Parameters

[out]	out_context	On success, will point to the new reverse trampoline context.
	signature	A null-terminated string describing the callback's signature.
	user_callback_fn	A function pointer to the user's generic closure handler. Its signature must match `infix_closure_handler_fn`.
	user_data	A user-defined pointer for passing state to the handler, accessible inside the handler via `infix_reverse_get_user_data(context)`.
	registry	An optional handle to a type registry. Pass `nullptr` if not used.

Returns: INFIX_SUCCESS on success.

Generates a low-level reverse-call trampoline (closure) from a signature string.

◆ infix_signature_parse()

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 infix_type parts.

This is an advanced function for callers who need to inspect type information before generating a trampoline. It creates a dedicated memory arena to hold the resulting infix_type object graph.

Parameters

[in]	signature	A null-terminated string describing the function signature.
[out]	out_arena	On success, points to the new arena owning the type graph.
[out]	out_ret_type	On success, points to the `infix_type` for the return value.
[out]	out_args	On success, points to an array of `infix_function_argument`.
[out]	out_num_args	On success, will be set to the total number of arguments.
[out]	out_num_fixed_args	On success, will be set to the number of non-variadic arguments.
[in]	registry	An optional handle to a type registry. Can be `nullptr`.

Returns: INFIX_SUCCESS if parsing is successful.

Note: Memory Management: On success, the caller takes ownership of the arena.

Parses a full function signature string into its constituent infix_type parts.

This function orchestrates the full process for parsing a complete function signature, including the lazy resolution pass if a registry is provided.

◆ infix_type_from_signature()

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.

A specialized parser for use cases like data marshalling or type inspection, where a full function signature is not needed.

Parameters

[out]	out_type	On success, will point to the newly created `infix_type`.
[out]	out_arena	On success, points to the new arena that owns the type graph.
[in]	signature	A string describing the data type (e.g., `"int32"`, `"{int, float}"`).
[in]	registry	An optional handle to a type registry. Can be `nullptr`.

Returns: INFIX_SUCCESS if parsing is successful.

Note: Memory Management: On success, the caller takes ownership of the arena.

Parses a signature string representing a single data type.

This function orchestrates the full process for parsing a single type:

Clears any previous thread-local error state.
Calls the internal parser to generate a raw type graph.
If a registry was provided, it calls the resolver to replace all @Name references with their concrete definitions.
On failure, it ensures all allocated resources are cleaned up.

Functions

Detailed Description

Function Documentation

◆ infix_forward_create()

◆ infix_forward_create_unbound()

◆ infix_reverse_create_callback()

◆ infix_reverse_create_closure()

◆ infix_signature_parse()

◆ infix_type_from_signature()