compile.h File Reference

Prepared compilers and module compilation. More...

Go to the source code of this file.

Data Structures
struct	loomc_compiler_options_t
	Compiler creation options. More...
struct	loomc_compile_options_t
	Compile invocation options. More...
struct	loomc_compile_artifact_options_t
	Complete target-artifact compilation options. More...

Typedefs
typedef struct loomc_compiler_t	loomc_compiler_t
	Prepared immutable compiler.
typedef uint32_t	loomc_compile_artifact_flags_t
	Bitmask of loomc_compile_artifact_flag_bits_t.

Enumerations
enum	loomc_compile_artifact_flag_bits_t { LOOMC_COMPILE_ARTIFACT_FLAG_MODULE_TEXT = 1u << 0 , LOOMC_COMPILE_ARTIFACT_FLAG_MODULE_BYTECODE = 1u << 1 , LOOMC_COMPILE_ARTIFACT_FLAG_REPORT_JSON = 1u << 2 , LOOMC_COMPILE_ARTIFACT_FLAG_LAUNCH_CONFIG = 1u << 3 }
	Compile artifact request bits. More...

Functions
loomc_status_t	loomc_compiler_create (loomc_context_t *context, const loomc_compiler_options_t *options, loomc_allocator_t allocator, loomc_compiler_t **out_compiler)
	Creates a prepared immutable compiler.
loomc_status_t	loomc_compile_module (loomc_compiler_t *compiler, loomc_workspace_t *workspace, const loomc_pass_program_t *pass_program, loomc_module_t *module, const loomc_compile_options_t *options, loomc_allocator_t allocator, loomc_result_t **out_result)
	Compiles a mutable module into in-memory artifacts.
loomc_status_t	loomc_compile_artifact (loomc_compiler_t *compiler, loomc_workspace_t *workspace, const loomc_pass_program_t *pass_program, loomc_module_t *module, const loomc_compile_artifact_options_t *options, loomc_allocator_t allocator, loomc_result_t **out_result)
	Compiles one mutable module through final target artifact emission.
loomc_status_t	loomc_compile_request (loomc_compiler_t *compiler, loomc_workspace_t *workspace, const loomc_pass_program_t *pass_program, const loomc_request_t *request, const loomc_compile_options_t *options, loomc_allocator_t allocator, loomc_product_t **out_product, loomc_result_t **out_result)
	Compiles one immutable leaf request into a compiler product.
const loomc_product_descriptor_t *	loomc_compiled_module_product_descriptor (void)
	Returns the process-local descriptor for products from loomc_compile_request.
void	loomc_compiler_retain (loomc_compiler_t *compiler)
	Retains a prepared compiler for another owner.
void	loomc_compiler_release (loomc_compiler_t *compiler)
	Releases a prepared compiler from one owner.

Detailed Description

Prepared compilers and module compilation.

A prepared compiler owns validated compile-time configuration and provider state. Compile invocations compose that compiler with a caller-selected prepared pass program, caller-owned workspace scratch, and a mutable module. Results return in-memory diagnostics, reports, and artifacts.

The core compile primitive accepts an already-formed loomc_module_t. Sources are deserialized into modules and indexes are linked into modules before compilation so each stage has independent options, diagnostics, and lifetime boundaries.

Example

Share prepared compiler state and keep scratch local to each worker:

void worker_main(loomc_compiler_t* compiler,
                 loomc_pass_program_t* pass_program) {
  loomc_compiler_retain(compiler);
  loomc_pass_program_retain(pass_program);
 
  loomc_workspace_t* workspace = NULL;
  loomc_status_t status =
      loomc_workspace_create(NULL, loomc_allocator_system(), &workspace);
  if (!loomc_status_is_ok(status)) {
    loomc_pass_program_release(pass_program);
    loomc_compiler_release(compiler);
    return;
  }
 
  // `config_module` is an ordinary module containing exact config.def
  // values. It may be deserialized from text or bytecode once and shared by
  // concurrent invocations.
  loomc_compile_options_t compile_options = {
      .type = LOOMC_STRUCTURE_TYPE_COMPILE_OPTIONS,
      .structure_size = sizeof(loomc_compile_options_t),
      .artifact_flags = LOOMC_COMPILE_ARTIFACT_FLAG_MODULE_BYTECODE |
                        LOOMC_COMPILE_ARTIFACT_FLAG_REPORT_JSON,
      .config_flags = LOOMC_CONFIG_POLICY_FLAG_REQUIRE_RESOLVED,
      .config_module = config_module,
  };
 
  // `module` is produced by deserialization, linking, or another module
  // operation. The compile invocation borrows it and may rewrite its IR, so
  // this worker owns exclusive access for the duration of the call. Reuse
  // compiler, pass program, and workspace for many independent module
  // invocations on this worker.
  loomc_result_t* result = NULL;
  status = loomc_compile_module(compiler, workspace, pass_program, module,
                                &compile_options,
                                loomc_allocator_system(), &result);
  if (loomc_status_is_ok(status)) {
    // Inspect diagnostics and artifacts through result.
    loomc_result_release(result);
  }
 
  loomc_workspace_release(workspace);
  loomc_pass_program_release(pass_program);
  loomc_compiler_release(compiler);
}

Typedef Documentation

loomc_compiler_t

typedef struct loomc_compiler_t loomc_compiler_t

Prepared immutable compiler.

A compiler is intended to be created once and reused across many invocations. It must not require repeated filesystem access on the hot path. Pass pipelines are prepared as loomc_pass_program_t handles and selected per invocation.

Thread safety

Prepared compilers are immutable after creation and may be shared across threads. Invocation-local scratch belongs in loomc_workspace_t.

Enumeration Type Documentation

loomc_compile_artifact_flag_bits_t

enum loomc_compile_artifact_flag_bits_t

Compile artifact request bits.

Enumerator
LOOMC_COMPILE_ARTIFACT_FLAG_MODULE_TEXT	Return textual Loom module IR after successful compilation.
LOOMC_COMPILE_ARTIFACT_FLAG_MODULE_BYTECODE	Return binary Loom bytecode after successful compilation.
LOOMC_COMPILE_ARTIFACT_FLAG_REPORT_JSON	Return a JSON compile report artifact. Reports are emitted for completed invocations, including failed results that still returned diagnostics.
LOOMC_COMPILE_ARTIFACT_FLAG_LAUNCH_CONFIG	Return the compiled host launch-config program for all kernel entries. The selected pass program must lower source kernel entries through the normal source-to-low boundary. The artifact contains one pure function per exported kernel and is loaded with loomc_launch_config_program_load.

Function Documentation

loomc_compile_artifact()

loomc_status_t loomc_compile_artifact	(	loomc_compiler_t *	compiler,
		loomc_workspace_t *	workspace,
		const loomc_pass_program_t *	pass_program,
		loomc_module_t *	module,
		const loomc_compile_artifact_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_result_t **	out_result )

Compiles one mutable module through final target artifact emission.

The operation verifies and configures the input, resolves and materializes one core compile request, executes one pass program, and emits through the request's selected target emitter. Diagnostics and all primary or sidecar artifacts share one result and preserve operation order.

Parameters

compiler	Prepared compiler whose context owns module.
workspace	Invocation-local scratch workspace.
pass_program	Optional prepared pass program. NULL selects the target emitter's default prepared-low pipeline. Pass an explicitly empty prepared program to perform no compiler transformations.
module	Mutable input module. Root materialization and compilation may replace or rewrite its internal IR while preserving the public handle.
options	Complete artifact options, or NULL for inferred roots, authored targets, empty configuration, and canonical emission.
allocator	Host allocator used for result and default-pipeline state.
out_result	Receives one retained result for the complete operation.

Returns

OK when the operation ran far enough to return a result. Non-OK statuses represent API misuse or infrastructure failure.

Ownership

The caller retains module and owns out_result on an OK return. The result owns its diagnostics and artifacts and is released with loomc_result_release.

Lifetime

The operation borrows every option view, profile, and prepared pass program only for the duration of the call. Returned data does not borrow them or the workspace.

Thread safety

Compiler, profile, and pass-program handles may be shared. Each concurrent invocation requires a distinct workspace and mutable module.

loomc_compile_module()

loomc_status_t loomc_compile_module	(	loomc_compiler_t *	compiler,
		loomc_workspace_t *	workspace,
		const loomc_pass_program_t *	pass_program,
		loomc_module_t *	module,
		const loomc_compile_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_result_t **	out_result )

Compiles a mutable module into in-memory artifacts.

Parameters

compiler	Prepared compiler.
workspace	Invocation-local scratch workspace.
pass_program	Prepared pass program selected for this invocation.
module	Module produced by deserialization, linking, or another module operation. The invocation borrows the module for the duration of the call and may rewrite its IR in place.
options	Compile invocation options, or NULL for defaults.
allocator	Host allocator used for result-owned storage.
out_result	Receives a retained result for the operation.

Returns

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

Ownership

The caller owns out_result on an OK return and releases it with loomc_result_release.

Postcondition

The caller retains ownership of module, and the module handle remains valid after the call. Its IR contents may have been transformed by the selected pass program. Callers needing independent later invocations of the original IR provide independent module storage before compilation. A successful target-specialized invocation also retains its concrete function-version facts in the module handle for a later loomc_emit_module call. Applied configuration bindings are copied into the module for later emission reports, even when compilation requests no report. Continuing compilation carries these products with their live functions; explicit target specialization refines the requested function contexts. A failed mutation clears the products. Cloning preserves the function products and applied bindings; IR serialization does not persist them.

Lifetime

Returned results and artifacts do not borrow from workspace and remain valid after loomc_workspace_trim. The invocation borrows options->config_module only for the duration of the call and does not mutate or retain it.

Artifact Requests

Artifact emission is opt-in through loomc_compile_options_t. Requesting module text or bytecode serializes the transformed module into result-owned bytes. Requesting a report returns a JSON artifact with invocation metadata, result state, diagnostic count, and the count of other artifacts emitted by the invocation.

Thread safety

Calls using the same compiler and pass program may run concurrently when each call uses a distinct workspace and distinct module, or when access to shared workspaces and modules is synchronized externally. The compiler and pass program are immutable after creation.

Target Specialization

loomc_target_specialization_options_t may be attached to loomc_compile_options_t::next. Direct specialization rows bind selected function versions to complete profiles. Target binding rows bind authored target.decl contexts and seed every function assigned to the declaration. All profiles must be compatible with the compiler context's target environment. Unrequested functions retain their authored targets, including generic targets, and targetless functions remain targetless.

loomc_compile_request()

loomc_status_t loomc_compile_request	(	loomc_compiler_t *	compiler,
		loomc_workspace_t *	workspace,
		const loomc_pass_program_t *	pass_program,
		const loomc_request_t *	request,
		const loomc_compile_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_product_t **	out_product,
		loomc_result_t **	out_result )

Compiles one immutable leaf request into a compiler product.

The request source is deserialized into workspace and compiled with the same pass program and invocation options as loomc_compile_module. The returned product owns the emitted artifact views and preserves request-root order as its exported-root order. It has no unresolved requirements.

This is the synchronous leaf operation used by a composing host after a cache miss. Cache hits bypass the operation entirely. Selecting the pass program remains the host's responsibility. Requests requiring this operation carry loomc_compiled_module_product_descriptor() as their process-local product contract without a target-kind enum.

Parameters

compiler	Prepared compiler.
workspace	Invocation-local scratch workspace.
pass_program	Prepared pass program selected for the request roots.
request	Immutable independently compilable request.
options	Compile invocation options, or NULL for defaults.
allocator	Host allocator used for the returned product and result.
out_product	Receives a retained product when the result succeeds; receives NULL when the result fails.
out_result	Receives a retained result for the operation.

Returns

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

Ownership

The caller owns out_product when non-NULL and releases it with loomc_product_release. The caller owns out_result on an OK return and releases it with loomc_result_release. The product does not retain request, its source, workspace, or the deserialized module. Result diagnostics may retain the request source when they reference it.

Thread safety

Calls may share compiler, pass_program, and request. Each concurrent call requires a distinct workspace.

loomc_compiled_module_product_descriptor()

const loomc_product_descriptor_t * loomc_compiled_module_product_descriptor

(

void

)

Returns the process-local descriptor for products from loomc_compile_request.

Returns

Process-lifetime compiled-module product descriptor.

loomc_compiler_create()

loomc_status_t loomc_compiler_create	(	loomc_context_t *	context,
		const loomc_compiler_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_compiler_t **	out_compiler )

Creates a prepared immutable compiler.

Parameters

context	Context shared with modules compiled by this compiler.
options	Compiler configuration, or NULL for defaults.
allocator	Host allocator used for compiler-owned storage.
out_compiler	Receives one retained compiler on success.

Returns

OK when the compiler was created.

Ownership

The caller owns the returned reference and releases it with loomc_compiler_release.

Thread safety

The returned compiler is immutable and may be shared across worker threads.

loomc_compiler_release()

void loomc_compiler_release

(

loomc_compiler_t *

compiler

)

Releases a prepared compiler from one owner.

Parameters

compiler

Compiler to release. Passing NULL is allowed.

Thread safety

Retain/release operations are intended to be safe from multiple threads. The compiler is destroyed when the final reference is released.

loomc_compiler_retain()

void loomc_compiler_retain

(

loomc_compiler_t *

compiler

)

Retains a prepared compiler for another owner.

Parameters

compiler

Compiler to retain.

Thread safety

Retain/release operations are intended to be safe from multiple threads.