interop.h File Reference

Exact-version interop between public LoomC handles and native Loom APIs. More...

Go to the source code of this file.

Data Structures
struct	loomc_module_interop_view_t
	Read-only native projection of a structurally verified LoomC module. More...
struct	loomc_module_mutable_interop_view_t
	Mutable native projection of a LoomC module for exact-version producers. More...
struct	loomc_native_pass_report_options_t
	Collects native pass invocation records during prepared execution. More...
struct	loomc_native_compile_report_options_t
	Collects target compilation details during prepared execution. More...

Functions
loomc_status_t	loomc_target_environment_create_from_provider_set (const loom_target_provider_set_t *provider_set, loomc_allocator_t allocator, loomc_target_environment_t **out_target_environment)
	Creates a public target environment from exact-version native providers.
loomc_status_t	loomc_target_environment_get_native_pass_registry (const loomc_target_environment_t *target_environment, loom_pass_registry_storage_t *out_storage)
	Composes builtin and target pass descriptors for exact-version inspection.
loomc_status_t	loomc_pass_program_create_from_native_source_low_pipeline (loomc_context_t *context, loom_target_pipeline_build_fn_t build_pipeline, loomc_string_view_t identifier, const loom_target_pipeline_options_t *options, loomc_allocator_t allocator, loomc_pass_program_t **out_pass_program, loomc_result_t **out_result)
	Creates a public pass program from a native source-Low pipeline builder.
loomc_status_t	loomc_module_get_interop_view (loomc_module_t *module, loomc_allocator_t allocator, loomc_module_interop_view_t *out_view, loomc_result_t **out_result)
	Verifies a public module and projects its native read-only view.
loomc_module_mutable_interop_view_t	loomc_module_get_mutable_interop_view (loomc_module_t *module)
	Projects a mutable native view after invalidating derived module state.
const loom_target_environment_t *	loomc_target_environment_get_interop_view (const loomc_target_environment_t *target_environment)
	Returns the immutable native environment owned by a public target handle.
const loom_target_profile_t *	loomc_target_profile_get_interop_view (const loomc_target_profile_t *target_profile)
	Returns the immutable native profile owned by a public target handle.

Detailed Description

Exact-version interop between public LoomC handles and native Loom APIs.

This optional adapter exposes compiler-native types and is intentionally not part of loomc/loomc.h or the stable LoomC ABI. The application, LoomC, and native Loom consumers must come from the same source revision and build configuration. Mixing versions or configurations is undefined behavior.

Function Documentation

loomc_module_get_interop_view()

loomc_status_t loomc_module_get_interop_view	(	loomc_module_t *	module,
		loomc_allocator_t	allocator,
		loomc_module_interop_view_t *	out_view,
		loomc_result_t **	out_result )

Verifies a public module and projects its native read-only view.

Structural invariants are always verified. When the module's context owns a target environment, target-Low legality is also verified against that environment. This makes the projected view safe for exact-version native consumers without duplicating the compiler's target verification contract.

Parameters

module	Module to verify and inspect.
allocator	Host allocator used for the returned result.
out_view	Receives a borrowed view when the result succeeds. Receives a zeroed view when verification fails.
out_result	Receives a retained verification result.

Returns

OK when verification ran to a result. Non-OK statuses represent API misuse or infrastructure failures before a result could be produced.

Ownership

The caller retains module and owns out_result on an OK return, releasing it with loomc_result_release.

Thread safety

This operation may establish cached verification state on module and requires exclusive access. The returned view may subsequently be read concurrently while no operation mutates the module.

loomc_module_get_mutable_interop_view()

loomc_module_mutable_interop_view_t loomc_module_get_mutable_interop_view

(

loomc_module_t *

module

)

Projects a mutable native view after invalidating derived module state.

This is an exact-version escape hatch for producers that construct or adapt Loom IR with native builder APIs before returning to public LoomC compilation. It performs no verification and returns a zero view when module is NULL or does not contain native IR.

Parameters

module

Module whose native IR will be mutated.

Returns

Borrowed mutable module and read-only source-table pointers.

Lifetime

The returned pointers remain valid until module is replaced, mutated by a public operation, or released. Concurrent access to module is invalid.

loomc_pass_program_create_from_native_source_low_pipeline()

loomc_status_t loomc_pass_program_create_from_native_source_low_pipeline	(	loomc_context_t *	context,
		loom_target_pipeline_build_fn_t	build_pipeline,
		loomc_string_view_t	identifier,
		const loom_target_pipeline_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_pass_program_t **	out_pass_program,
		loomc_result_t **	out_result )

Creates a public pass program from a native source-Low pipeline builder.

This bridge lets an exact-version embedding select a native source-Low inspection boundary without serializing pass IR or adding presentation-only pipeline variants to the stable LoomC target-pipeline enum. The builder is invoked once while preparing the immutable pass program.

Parameters

context	Public context whose target environment supplies native target and pass capabilities.
build_pipeline	Native source-Low pipeline builder to invoke.
identifier	Stable pipeline symbol and diagnostic identifier.
options	Native target pipeline options borrowed during preparation. May be NULL for builder defaults.
allocator	Host allocator used for pass-program and result storage.
out_pass_program	Receives one retained pass program when the result succeeds. Receives NULL when preparation fails.
out_result	Receives one retained preparation result.

Returns

OK when preparation ran to a result. Non-OK statuses represent API misuse or infrastructure failure.

Ownership

The caller owns both returned handles and releases them with loomc_pass_program_release and loomc_result_release.

loomc_target_environment_create_from_provider_set()

loomc_status_t loomc_target_environment_create_from_provider_set	(	const loom_target_provider_set_t *	provider_set,
		loomc_allocator_t	allocator,
		loomc_target_environment_t **	out_target_environment )

Creates a public target environment from exact-version native providers.

This lets a final embedding binary compose its linked native target providers once while leaving environment construction and ownership with LoomC. Native consumers can borrow the resulting environment with loomc_target_environment_get_interop_view.

Parameters

provider_set	Native target providers to compose.
allocator	Host allocator used for public handle storage.
out_target_environment	Receives one retained public target handle.

Returns

OK when the environment and pass capabilities were prepared.

Ownership

The returned handle owns the composed target environment. The caller owns the handle and releases it with loomc_target_environment_release.

Lifetime

provider_set and every provider it references must remain valid until the returned handle and every object derived from it have been released.

loomc_target_environment_get_interop_view()

const loom_target_environment_t * loomc_target_environment_get_interop_view

(

const loomc_target_environment_t *

target_environment

)

Returns the immutable native environment owned by a public target handle.

Parameters

target_environment

Target environment to inspect. May be NULL.

Returns

Borrowed native environment, or NULL when the input is NULL.

Lifetime

The returned pointer remains valid until target_environment is released.

loomc_target_environment_get_native_pass_registry()

loomc_status_t loomc_target_environment_get_native_pass_registry	(	const loomc_target_environment_t *	target_environment,
		loom_pass_registry_storage_t *	out_storage )

Composes builtin and target pass descriptors for exact-version inspection.

This is the same registry used to prepare pass programs. It lets clients present pass names, descriptions, and option schemas without linking the builtin pass implementations. No context or heap allocation is required.

Parameters

target_environment	Environment supplying target-specific passes. May be NULL to inspect builtin passes alone.
out_storage	Caller-owned storage receiving the composed registry.

Returns

OK on success; non-OK if the provider registries cannot be composed.

Lifetime

The storage must remain at a stable address while its registry is used. Descriptors borrow from the target providers; retain the environment until inspection is complete. The registry has the exact-version native contract of this header, including native callback types, and is not a stable ABI.

loomc_target_profile_get_interop_view()

const loom_target_profile_t * loomc_target_profile_get_interop_view

(

const loomc_target_profile_t *

target_profile

)

Returns the immutable native profile owned by a public target handle.

Parameters

target_profile

Target profile to inspect. May be NULL.

Returns

Borrowed native profile, or NULL when the input is NULL.

Lifetime

The returned pointer remains valid until target_profile is released.