cxx.h File Reference

Optional native C/C++ source import into ordinary Loom modules. More...

Go to the source code of this file.

Data Structures
struct	loomc_cxx_source_provider_t
	Optional source provider replacing filesystem include reads. More...
struct	loomc_cxx_source_path_mapper_t
	Optional logical-identity mapper for retained frontend source paths. More...
struct	loomc_cxx_define_t
	Preprocessor definition applied after the frontend's predefined macros. More...
struct	loomc_cxx_import_options_t
	Configuration for one source translation unit. More...

Typedefs
typedef uint32_t	loomc_cxx_import_flags_t
	Bitmask of loomc_cxx_import_flag_bits_t values.
typedef loomc_status_t(*	loomc_cxx_source_provider_fn_t) (void *user_data, loomc_string_view_t path, loomc_source_t **out_source)
	Resolves a candidate include path to immutable source bytes.
typedef loomc_status_t(*	loomc_cxx_source_path_mapper_fn_t) (void *user_data, loomc_string_view_t path, loomc_string_view_t *out_identifier)
	Maps a physical frontend path to the logical source identifier retained in diagnostics and imported modules.
typedef struct loomc_cxx_preamble_t	loomc_cxx_preamble_t
	Immutable process-local C/C++ semantic preamble.

Enumerations
enum	loomc_cxx_data_model_t { LOOMC_CXX_DATA_MODEL_LP64 = 0 , LOOMC_CXX_DATA_MODEL_LLP64 = 1 , LOOMC_CXX_DATA_MODEL_ILP32 = 2 }
	Source integer and pointer layout, independent of the importing process. More...
enum	loomc_cxx_fp_model_t { LOOMC_CXX_FP_MODEL_PRECISE = 0 , LOOMC_CXX_FP_MODEL_FAST = 1 }
	Translation-unit floating-point transformation policy. More...
enum	loomc_cxx_import_flag_bits_t { LOOMC_CXX_IMPORT_FLAG_NO_BUILTIN_INCLUDES = 1u << 0 }
	Include delivery policy. More...

Functions
loomc_status_t	loomc_cxx_preamble_create (loomc_context_t *context, const loomc_source_t *source, const loomc_cxx_import_options_t *options, loomc_allocator_t allocator, loomc_cxx_preamble_t **out_preamble, loomc_result_t **out_result)
	Creates an immutable semantic preamble from leading include directives.
void	loomc_cxx_preamble_retain (loomc_cxx_preamble_t *preamble)
	Retains preamble for another owner.
void	loomc_cxx_preamble_release (loomc_cxx_preamble_t *preamble)
	Releases preamble from one owner.
loomc_status_t	loomc_module_import_cxx (loomc_context_t *context, loomc_workspace_t *workspace, const loomc_source_t *source, const loomc_cxx_import_options_t *options, loomc_allocator_t allocator, loomc_module_t **out_module, loomc_result_t **out_result)
	Imports C/C++ source into a verified High IR module, without cleanup passes.

Detailed Description

Optional native C/C++ source import into ordinary Loom modules.

One configured translation unit produces one compilation-unit module. Multiple kernels and ordinary functions share the module. Build scheduling, host/device partitioning, and linking remain above this interface.

The implementation uses the standalone cxx frontend and native Loom APIs; no LLVM or Python runtime is required. Enable the cxx importer package when building the library and link the optional import/cxx component.

Typedef Documentation

loomc_cxx_preamble_t

typedef struct loomc_cxx_preamble_t loomc_cxx_preamble_t

Immutable process-local C/C++ semantic preamble.

A preamble owns the parsed state and exact source snapshot of one leading include prefix. It does not retain the source, context, import options, or callback state used to create it. Retained handles may be shared by concurrent imports; each import restores into a fresh translation unit.

loomc_cxx_source_path_mapper_fn_t

typedef loomc_status_t(* loomc_cxx_source_path_mapper_fn_t) (void *user_data, loomc_string_view_t path, loomc_string_view_t *out_identifier)

Maps a physical frontend path to the logical source identifier retained in diagnostics and imported modules.

The physical path remains the identity used for include lookup. Returning the same logical identifier for distinct physical sources is invalid.

Parameters

user_data	Caller state from the mapper descriptor.
path	Physical frontend path borrowed for this callback.
out_identifier	Receives the logical diagnostic/module identity.

Returns

OK when the path was mapped, or a mapping failure status.

Lifetime

The returned identifier must remain valid until the next mapper callback. The importer copies it before another callback can occur.

Thread safety

Calls are synchronous and sequential within one import. A mapper shared by concurrent imports must synchronize its own mutable state.

loomc_cxx_source_provider_fn_t

typedef loomc_status_t(* loomc_cxx_source_provider_fn_t) (void *user_data, loomc_string_view_t path, loomc_source_t **out_source)

Resolves a candidate include path to immutable source bytes.

Paths follow ordinary quote, user, system, and include_next search rules. Candidate paths use generic '/' separators on every host. Return OK with a NULL output for a missing candidate. Other failures return status with a NULL output. A found source uses UNKNOWN format; its contents supply the header and the candidate path determines include identity.

Parameters

user_data	Caller state from the provider descriptor.
path	Candidate path borrowed for this callback.
out_source	Receives one retained source or NULL for a missing path.

Returns

OK for found/missing candidates, or a provider failure status.

Ownership

A successful non-NULL output transfers one retained reference to the importer. A cache can retain its own reference and return another. The importer releases the reference once it has copied the bytes.

Thread safety

Calls are synchronous and sequential within one import. A provider shared by concurrent imports must synchronize its own mutable state.

Enumeration Type Documentation

loomc_cxx_data_model_t

enum loomc_cxx_data_model_t

Source integer and pointer layout, independent of the importing process.

Enumerator
LOOMC_CXX_DATA_MODEL_LP64	32-bit int; 64-bit long and pointers.
LOOMC_CXX_DATA_MODEL_LLP64	32-bit int and long; 64-bit pointers.
LOOMC_CXX_DATA_MODEL_ILP32	32-bit int, long, and pointers.

loomc_cxx_fp_model_t

enum loomc_cxx_fp_model_t

Translation-unit floating-point transformation policy.

Source fastmath attributes may replace this default for individual functions or statements.

Enumerator
LOOMC_CXX_FP_MODEL_PRECISE	Preserve floating-point value and evaluation-order semantics.
LOOMC_CXX_FP_MODEL_FAST	Permit the complete Loom fast-math contract.

loomc_cxx_import_flag_bits_t

enum loomc_cxx_import_flag_bits_t

Include delivery policy.

Enumerator
LOOMC_CXX_IMPORT_FLAG_NO_BUILTIN_INCLUDES	Omit the embedded system include root; use caller paths/providers only.

Function Documentation

loomc_cxx_preamble_create()

loomc_status_t loomc_cxx_preamble_create	(	loomc_context_t *	context,
		const loomc_source_t *	source,
		const loomc_cxx_import_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_cxx_preamble_t **	out_preamble,
		loomc_result_t **	out_result )

Creates an immutable semantic preamble from leading include directives.

The representative source must begin with at least one reusable include. The handle copies its matching source prefix, resolved headers, retained misses, and serialized frontend state. Later imports can vary source text after that prefix and import-only policy such as roots or floating-point lowering while retaining the same language, ABI, include-search, define, and embedded-header configuration.

Parameters

context	Immutable context defining diagnostic source retention.
source	Representative source with UNKNOWN format.
options	Source configuration, or NULL for defaults.
allocator	Host allocator owning the returned handle and result.
out_preamble	Receives one owned preamble after successful admission.
out_result	Receives one owned result with retained diagnostics.

Returns

OK for successful creation or diagnosed source rejection. Rejection returns a failed result and NULL preamble. A source without a leading include returns FAILED_PRECONDITION with NULL outputs.

Ownership

Release outputs with loomc_cxx_preamble_release and loomc_result_release. The caller owns catalog lookup, caching, and eviction policy.

Lifetime

Source/include bytes, options, and callback state may be released on return. The returned handle is process-local and has no persisted wire format.

Thread safety

The immutable handle may be retained, released, and used by concurrent imports. The source provider and path mapper follow their documented per-invocation synchronization requirements during creation.

loomc_cxx_preamble_release()

void loomc_cxx_preamble_release

(

loomc_cxx_preamble_t *

preamble

)

Releases preamble from one owner.

Passing NULL is allowed.

Parameters

preamble

Preamble to release, or NULL.

The immutable preamble is destroyed after its final reference is released.

loomc_cxx_preamble_retain()

void loomc_cxx_preamble_retain

(

loomc_cxx_preamble_t *

preamble

)

Retains preamble for another owner.

Passing NULL is allowed.

Parameters

preamble

Preamble to retain, or NULL.

Retain/release operations are safe to perform from multiple threads.

loomc_module_import_cxx()

loomc_status_t loomc_module_import_cxx	(	loomc_context_t *	context,
		loomc_workspace_t *	workspace,
		const loomc_source_t *	source,
		const loomc_cxx_import_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_module_t **	out_module,
		loomc_result_t **	out_result )

Imports C/C++ source into a verified High IR module, without cleanup passes.

Parameters

context	Immutable context containing the core dialects.
workspace	Workspace backing the returned module's arena storage.
source	Source with UNKNOWN format. Its identifier labels diagnostics and supplies the main file's path for quoted include lookup.
options	Source configuration, or NULL for defaults.
allocator	Host allocator for public handles and temporary adapters.
out_module	Receives one owned module on successful source admission.
out_result	Receives one owned result with retained diagnostics.

Returns

OK for successful import or diagnosed source rejection. Rejection returns a failed result and NULL module. Infrastructure/API failures return non-OK status and NULL outputs. C++ exceptions never cross this boundary.

Ownership

Release outputs with loomc_module_release and loomc_result_release. The module retains its context/workspace. The result owns diagnostic contents.

Lifetime

Source/include bytes, options, and callback state may be released on return. Neither the module nor the result retains borrowed frontend or AST storage.

Thread safety

Each import requires exclusive access to its workspace. Concurrent imports may share an immutable context and immutable source handles.