link.h File Reference

Linker and opaque linked-module handles. More...

Go to the source code of this file.

Data Structures
struct	loomc_linker_options_t
	Linker creation options. More...
struct	loomc_link_options_t
	Link invocation options. More...
struct	loomc_link_request_options_t
	Request-linking options. More...

Typedefs
typedef struct loomc_linker_t	loomc_linker_t
	Prepared immutable linker.
typedef uint32_t	loomc_link_flags_t
	Bitmask of loomc_link_flag_bits_t values.

Enumerations
enum	loomc_link_flag_bits_t { LOOMC_LINK_FLAG_INCLUDE_INPUT_EXPORTS = 1u << 0 , LOOMC_LINK_FLAG_ALLOW_UNRESOLVED_SYMBOLS = 1u << 1 , LOOMC_LINK_FLAG_STRIP_TEST_SYMBOLS = 1u << 2 }
	Link operation flags. More...
enum	loomc_link_mode_t { LOOMC_LINK_MODE_MERGE = 0 , LOOMC_LINK_MODE_LINK = 1 }
	Link product selection mode. More...

Functions
loomc_status_t	loomc_linker_create (loomc_context_t *context, const loomc_linker_options_t *options, loomc_allocator_t allocator, loomc_linker_t **out_linker)
	Creates a prepared immutable linker.
loomc_status_t	loomc_link_module (loomc_linker_t *linker, loomc_workspace_t *workspace, const loomc_link_options_t *options, loomc_module_t **out_module, loomc_result_t **out_result)
	Links a frozen index into an opaque module.
loomc_status_t	loomc_link_request (loomc_linker_t *linker, loomc_workspace_t *workspace, const loomc_request_t *input_request, const loomc_link_request_options_t *options, loomc_allocator_t allocator, loomc_request_t **out_request, loomc_result_t **out_result)
	Seals an ordinary request against an optional frozen library index.
void	loomc_linker_retain (loomc_linker_t *linker)
	Retains a prepared linker for another owner.
void	loomc_linker_release (loomc_linker_t *linker)
	Releases a prepared linker from one owner.

Detailed Description

Linker and opaque linked-module handles.

Linking resolves primary sources/modules against reusable frozen indexes and produces an opaque module handle that can be consumed by later API operations without printing and reparsing text. The optimized embedding path prepares linkers and indexes once, then invokes them many times with per-worker workspaces.

Example

Link a reusable index with an invocation-local workspace:

loomc_linker_t* linker = NULL;
loomc_status_t status = loomc_linker_create(
    context, NULL, loomc_allocator_system(), &linker);
if (!loomc_status_is_ok(status)) return status;
 
loomc_workspace_t* workspace = NULL;
status = loomc_workspace_create(NULL, loomc_allocator_system(), &workspace);
if (!loomc_status_is_ok(status)) {
  loomc_linker_release(linker);
  return status;
}
 
const loomc_string_view_t roots[] = {
    loomc_make_cstring_view("@entry"),
};
loomc_link_options_t link_options = {
    .type = LOOMC_STRUCTURE_TYPE_LINK_OPTIONS,
    .structure_size = sizeof(loomc_link_options_t),
    .link_index = library_index,
    .mode = LOOMC_LINK_MODE_LINK,
    .root_symbols = roots,
    .root_symbol_count = 1,
};
 
loomc_module_t* module = NULL;
loomc_result_t* result = NULL;
status = loomc_link_module(
    linker, workspace, &link_options, &module, &result);
if (loomc_status_is_ok(status) && loomc_result_succeeded(result)) {
  // Pass module to compile without a text round trip.
}
loomc_result_release(result);
loomc_module_release(module);
loomc_workspace_release(workspace);
loomc_linker_release(linker);

Typedef Documentation

loomc_linker_t

typedef struct loomc_linker_t loomc_linker_t

Prepared immutable linker.

A linker owns validated link-time configuration. Frozen indexes carry reusable provider state and are supplied per invocation.

Thread safety

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

Enumeration Type Documentation

loomc_link_flag_bits_t

enum loomc_link_flag_bits_t

Link operation flags.

Enumerator
LOOMC_LINK_FLAG_INCLUDE_INPUT_EXPORTS	Select exported INPUT-provider symbols as roots and compute their closure.
LOOMC_LINK_FLAG_ALLOW_UNRESOLVED_SYMBOLS	Preserve reachable unresolved references for a later link or specialization step.
LOOMC_LINK_FLAG_STRIP_TEST_SYMBOLS	Strip symbols used only by test or benchmark tooling.

loomc_link_mode_t

enum loomc_link_mode_t

Link product selection mode.

Enumerator
LOOMC_LINK_MODE_MERGE	Merge every primary-input symbol into one relocatable module. Library providers are not materialized.
LOOMC_LINK_MODE_LINK	Retain explicit roots or exported primary-input roots and their reachable closure through the complete supplied library universe. Selected root providers contribute all of their exported symbols as roots without changing provider visibility.

Function Documentation

loomc_link_module()

loomc_status_t loomc_link_module	(	loomc_linker_t *	linker,
		loomc_workspace_t *	workspace,
		const loomc_link_options_t *	options,
		loomc_module_t **	out_module,
		loomc_result_t **	out_result )

Links a frozen index into an opaque module.

Parameters

linker	Prepared linker.
workspace	Invocation-local scratch workspace.
options	Link invocation options.
out_module	Receives a retained linked module when the result succeeds. Receives NULL when the result fails.
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_module when non-NULL and releases it with loomc_module_release. The caller always owns out_result on an OK return and releases it with loomc_result_release.

Lifetime

Returned results do not borrow from workspace and remain valid after loomc_workspace_trim. Returned modules retain workspace and keep their arena blocks live until released.

Thread safety

Calls using the same linker may run concurrently when each call uses a distinct workspace. The same workspace requires external synchronization.

loomc_link_request()

loomc_status_t loomc_link_request	(	loomc_linker_t *	linker,
		loomc_workspace_t *	workspace,
		const loomc_request_t *	input_request,
		const loomc_link_request_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_request_t **	out_request,
		loomc_result_t **	out_result )

Seals an ordinary request against an optional frozen library index.

Parameters

linker	Prepared linker.
workspace	Invocation-local scratch workspace.
input_request	Immutable ordinary bytecode request to link.
options	Request-linking options, or NULL for a source-only link.
allocator	Host allocator owning the returned request and result.
out_request	Receives an independently owned linked request when the result succeeds. Receives NULL when the result fails.
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_request when non-NULL and releases it with loomc_request_release. The caller always owns out_result on an OK return and releases it with loomc_result_release.

Lifetime

The returned request owns standalone bytecode and does not retain input_request, options->library_index, or workspace. It remains valid after those objects are released or trimmed.

Thread safety

Calls using the same linker and frozen library index may run concurrently when each call uses a distinct workspace. The same workspace requires external synchronization.

Error contract

Malformed request bytecode, unresolved link contracts, invalid source IR, and specialization failures produce OK status plus a failed result with diagnostics. Structural request inconsistencies and API misuse produce a non-OK status without a result.

loomc_linker_create()

loomc_status_t loomc_linker_create	(	loomc_context_t *	context,
		const loomc_linker_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_linker_t **	out_linker )

Creates a prepared immutable linker.

Parameters

context	Context shared with all link indexes used by this linker.
options	Linker configuration, or NULL for defaults.
allocator	Host allocator used for linker-owned storage.
out_linker	Receives one retained linker on success.

Returns

OK when the linker was created.

Ownership

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

Thread safety

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

loomc_linker_release()

void loomc_linker_release

(

loomc_linker_t *

linker

)

Releases a prepared linker from one owner.

Parameters

linker

Linker to release. Passing NULL is allowed.

Thread safety

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

loomc_linker_retain()

void loomc_linker_retain

(

loomc_linker_t *

linker

)

Retains a prepared linker for another owner.

Parameters

linker

Linker to retain.

Thread safety

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