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

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_EXPORTED_ROOTS = 1u << 0 , LOOMC_LINK_FLAG_ALLOW_UNRESOLVED_SYMBOLS = 1u << 1 , LOOMC_LINK_FLAG_STRIP_TEST_SYMBOLS = 1u << 2 }
	Link operation flags. 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.
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,
    .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_EXPORTED_ROOTS	Select exported symbols as roots and compute their dependency closure.
LOOMC_LINK_FLAG_ALLOW_UNRESOLVED_SYMBOLS	Leave unresolved references for later verification or specialization.
LOOMC_LINK_FLAG_STRIP_TEST_SYMBOLS	Strip symbols used only by test or benchmark tooling.

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