Reusable link indexes for deterministic library and source discovery. More...

Data Structures
struct	loomc_link_index_builder_options_t
	Link-index builder creation options. More...
struct	loomc_link_index_source_slot_t
	Deterministic source slot reserved by a link-index builder. More...
struct	loomc_link_index_source_options_t
	Source provider options used when adding sources to a link index. More...
struct	loomc_link_index_provider_t
	Indexed provider metadata. More...
struct	loomc_link_index_module_t
	Indexed module metadata. More...
struct	loomc_link_index_symbol_t
	Indexed symbol metadata. More...

Typedefs
typedef struct loomc_link_index_builder_t	loomc_link_index_builder_t
	Mutable builder used to construct a frozen link index.
typedef struct loomc_link_index_t	loomc_link_index_t
	Frozen immutable link index.
typedef uint32_t	loomc_link_symbol_flags_t
	Bitmask of loomc_link_symbol_flag_bits_t values.

Enumerations
enum	loomc_link_provider_role_t { LOOMC_LINK_PROVIDER_ROLE_INPUT = 0 , LOOMC_LINK_PROVIDER_ROLE_LIBRARY = 1 }
	Search role assigned to a source provider in a link index. More...
enum	loomc_link_provider_kind_t { LOOMC_LINK_PROVIDER_KIND_UNKNOWN = 0 , LOOMC_LINK_PROVIDER_KIND_TEXT = 1 , LOOMC_LINK_PROVIDER_KIND_BYTECODE = 2 , LOOMC_LINK_PROVIDER_KIND_MATERIALIZED = 3 }
	Source representation kind recorded for an indexed provider. More...
enum	loomc_link_symbol_identity_t { LOOMC_LINK_SYMBOL_IDENTITY_PRIVATE = 0 , LOOMC_LINK_SYMBOL_IDENTITY_GLOBAL = 1 }
	Linker-facing symbol identity class. More...
enum	loomc_link_symbol_kind_t { LOOMC_LINK_SYMBOL_KIND_UNKNOWN = 0 , LOOMC_LINK_SYMBOL_KIND_FUNCTION_DEFINITION = 1 , LOOMC_LINK_SYMBOL_KIND_FUNCTION_DECLARATION = 2 , LOOMC_LINK_SYMBOL_KIND_FUNCTION_TEMPLATE = 3 , LOOMC_LINK_SYMBOL_KIND_FUNCTION_UKERNEL = 4 , LOOMC_LINK_SYMBOL_KIND_GLOBAL = 5 , LOOMC_LINK_SYMBOL_KIND_EXECUTABLE = 6 , LOOMC_LINK_SYMBOL_KIND_RECORD = 7 }
	Linker-facing symbol kind. More...
enum	loomc_link_symbol_flag_bits_t { LOOMC_LINK_SYMBOL_FLAG_PUBLIC = 1u << 0 , LOOMC_LINK_SYMBOL_FLAG_IMPORT = 1u << 1 , LOOMC_LINK_SYMBOL_FLAG_EXPORT = 1u << 2 , LOOMC_LINK_SYMBOL_FLAG_DECLARATION = 1u << 3 , LOOMC_LINK_SYMBOL_FLAG_HAS_BODY = 1u << 4 , LOOMC_LINK_SYMBOL_FLAG_CONFIG = 1u << 5 , LOOMC_LINK_SYMBOL_FLAG_TEST_ONLY = 1u << 6 }
	Link-index symbol flag bit values. More...

Functions
loomc_status_t	loomc_link_index_builder_create (loomc_context_t context, const loomc_link_index_builder_options_t options, loomc_allocator_t allocator, loomc_link_index_builder_t **out_builder)
	Creates an empty link-index builder.
void	loomc_link_index_builder_release (loomc_link_index_builder_t *builder)
	Releases a link-index builder.
loomc_status_t	loomc_link_index_builder_reserve_source_slot (loomc_link_index_builder_t builder, const loomc_link_index_source_options_t options, loomc_link_index_source_slot_t *out_slot)
	Reserves a deterministic source slot.
loomc_status_t	loomc_link_index_builder_fill_source_slot (loomc_link_index_builder_t builder, loomc_link_index_source_slot_t slot, loomc_source_t source)
	Fills an already reserved source slot.
loomc_status_t	loomc_link_index_builder_add_source (loomc_link_index_builder_t builder, loomc_source_t source, const loomc_link_index_source_options_t options, loomc_link_index_source_slot_t out_slot)
	Reserves and fills the next source slot.
loomc_status_t	loomc_link_index_builder_finish (loomc_link_index_builder_t builder, loomc_link_index_t out_link_index, loomc_result_t *out_result)
	Finishes a builder into a frozen immutable link index.
void	loomc_link_index_retain (loomc_link_index_t *link_index)
	Retains a frozen link index for another owner.
void	loomc_link_index_release (loomc_link_index_t *link_index)
	Releases a frozen link index from one owner.
loomc_host_size_t	loomc_link_index_provider_count (const loomc_link_index_t *link_index)
	Returns the number of providers in a frozen index.
bool	loomc_link_index_provider_at (const loomc_link_index_t link_index, loomc_host_size_t ordinal, loomc_link_index_provider_t out_provider)
	Returns provider metadata by ordinal.
loomc_host_size_t	loomc_link_index_module_count (const loomc_link_index_t *link_index)
	Returns the number of modules in a frozen index.
bool	loomc_link_index_module_at (const loomc_link_index_t link_index, loomc_host_size_t ordinal, loomc_link_index_module_t out_module)
	Returns module metadata by ordinal.
loomc_host_size_t	loomc_link_index_symbol_count (const loomc_link_index_t *link_index)
	Returns the number of symbols in a frozen index.
bool	loomc_link_index_symbol_at (const loomc_link_index_t link_index, loomc_host_size_t ordinal, loomc_link_index_symbol_t out_symbol)
	Returns symbol metadata by ordinal.
bool	loomc_link_index_lookup_global (const loomc_link_index_t link_index, loomc_string_view_t name, loomc_link_index_symbol_t out_symbol)
	Looks up the selected global symbol by name.
bool	loomc_link_index_next_global_duplicate (const loomc_link_index_t link_index, const loomc_link_index_symbol_t symbol, loomc_link_index_symbol_t *out_symbol)
	Returns the next duplicate global symbol for symbol.
bool	loomc_link_index_lookup_private (const loomc_link_index_t link_index, const loomc_link_index_module_t module, loomc_string_view_t name, loomc_link_index_symbol_t *out_symbol)
	Looks up a private symbol within an indexed module.

Detailed Description

Reusable link indexes for deterministic library and source discovery.

A frozen link index records source/provider identity and symbol metadata so link operations can resolve live roots without rebuilding reusable library indexes. Builders reserve deterministic source slots, accept source handles in any slot order, and finish into an immutable, shareable index whose provider order is independent of scheduling order.

The first indexing contract is intentionally explicit about lifetimes: source handles are retained by the builder, and a frozen index owns the persistent storage needed for provider/module/symbol metadata. Resetting a caller workspace never invalidates a frozen link index.

Example: Retain a frozen library index when handing it to an asynchronous worker:

void schedule_worker(loomc_link_index_t* library_index) {
  loomc_link_index_retain(library_index);
  // `enqueue_work` is application-owned scheduling policy.
  enqueue_work(library_index);
}
 
void worker_main(loomc_link_index_t* library_index) {
  // Use library_index with a per-worker workspace and prepared linker.
  loomc_link_index_release(library_index);
}

Typedef Documentation

◆ loomc_link_index_builder_t

typedef struct loomc_link_index_builder_t loomc_link_index_builder_t

Mutable builder used to construct a frozen link index.

Thread safety: Reserving slots and finishing a builder require exclusive access. Distinct already-reserved slots may be filled concurrently when each slot is filled by at most one thread and no thread calls finish until all fills have joined.

◆ loomc_link_index_t

typedef struct loomc_link_index_t loomc_link_index_t

Frozen immutable link index.

Thread safety: Frozen indexes are immutable and may be shared by many linker invocations across many threads.

Enumeration Type Documentation

◆ loomc_link_provider_kind_t

enum loomc_link_provider_kind_t

Source representation kind recorded for an indexed provider.

Enumerator
LOOMC_LINK_PROVIDER_KIND_UNKNOWN	Provider kind is unknown.
LOOMC_LINK_PROVIDER_KIND_TEXT	Provider was indexed from text .loom source.
LOOMC_LINK_PROVIDER_KIND_BYTECODE	Provider was indexed from bytecode .loombc source.
LOOMC_LINK_PROVIDER_KIND_MATERIALIZED	Provider was indexed from an already materialized module.

◆ loomc_link_provider_role_t

enum loomc_link_provider_role_t

Search role assigned to a source provider in a link index.

Enumerator
LOOMC_LINK_PROVIDER_ROLE_INPUT	Primary input providers are selected before libraries.
LOOMC_LINK_PROVIDER_ROLE_LIBRARY	Library providers are searched after primary inputs.

◆ loomc_link_symbol_flag_bits_t

enum loomc_link_symbol_flag_bits_t

Link-index symbol flag bit values.

Enumerator
LOOMC_LINK_SYMBOL_FLAG_PUBLIC	Symbol is publicly visible in its source module.
LOOMC_LINK_SYMBOL_FLAG_IMPORT	Symbol is an import declaration supplied by another provider/module.
LOOMC_LINK_SYMBOL_FLAG_EXPORT	Symbol is exported from its provider/module.
LOOMC_LINK_SYMBOL_FLAG_DECLARATION	Symbol is declaration-like and may be superseded by a concrete definition.
LOOMC_LINK_SYMBOL_FLAG_HAS_BODY	Symbol has materializable IR owned by its provider.
LOOMC_LINK_SYMBOL_FLAG_CONFIG	Symbol implements the config symbol interface.
LOOMC_LINK_SYMBOL_FLAG_TEST_ONLY	Symbol exists only for test or benchmark tooling.

◆ loomc_link_symbol_identity_t

enum loomc_link_symbol_identity_t

Linker-facing symbol identity class.

Enumerator
LOOMC_LINK_SYMBOL_IDENTITY_PRIVATE	Symbol identity is scoped to one provider-local module.
LOOMC_LINK_SYMBOL_IDENTITY_GLOBAL	Symbol identity is resolved by name across providers.

◆ loomc_link_symbol_kind_t

enum loomc_link_symbol_kind_t

Linker-facing symbol kind.

Enumerator
LOOMC_LINK_SYMBOL_KIND_UNKNOWN	Symbol kind is unknown.
LOOMC_LINK_SYMBOL_KIND_FUNCTION_DEFINITION	Function definition with a body.
LOOMC_LINK_SYMBOL_KIND_FUNCTION_DECLARATION	Function declaration or import.
LOOMC_LINK_SYMBOL_KIND_FUNCTION_TEMPLATE	Function template.
LOOMC_LINK_SYMBOL_KIND_FUNCTION_UKERNEL	Microkernel implementation.
LOOMC_LINK_SYMBOL_KIND_GLOBAL	Global value or configuration symbol.
LOOMC_LINK_SYMBOL_KIND_EXECUTABLE	Executable/package symbol.
LOOMC_LINK_SYMBOL_KIND_RECORD	Record symbol.

Function Documentation

◆ loomc_link_index_builder_add_source()

loomc_status_t loomc_link_index_builder_add_source	(	loomc_link_index_builder_t *	builder,
		loomc_source_t *	source,
		const loomc_link_index_source_options_t *	options,
		loomc_link_index_source_slot_t *	out_slot )

Reserves and fills the next source slot.

Parameters

builder	Builder to mutate.
source	Source retained by the builder on success.
options	Provider options copied by this call, or NULL for defaults.
out_slot	Receives the source slot, or NULL if not needed.

Returns: OK when the source was queued for indexing.

◆ loomc_link_index_builder_create()

loomc_status_t loomc_link_index_builder_create	(	loomc_context_t *	context,
		const loomc_link_index_builder_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_link_index_builder_t **	out_builder )

Creates an empty link-index builder.

Parameters

context	Reusable Loom API context retained by the builder.
options	Builder options, or NULL for defaults.
allocator	Host allocator used for builder and frozen-index storage.
out_builder	Receives the mutable builder on success.

Returns: OK when the builder was created.

Ownership: The caller owns the returned builder and releases it with loomc_link_index_builder_release.

◆ loomc_link_index_builder_fill_source_slot()

loomc_status_t loomc_link_index_builder_fill_source_slot	(	loomc_link_index_builder_t *	builder,
		loomc_link_index_source_slot_t	slot,
		loomc_source_t *	source )

Fills an already reserved source slot.

Parameters

builder	Builder that owns slot.
slot	Source slot previously returned by loomc_link_index_builder_reserve_source_slot.
source	Source retained by the builder on success.

Returns: OK when the slot was filled.

Thread safety: Distinct reserved slots may be filled concurrently when each slot is filled by at most one thread and no thread calls reserve or finish concurrently.

◆ loomc_link_index_builder_finish()

loomc_status_t loomc_link_index_builder_finish	(	loomc_link_index_builder_t *	builder,
		loomc_link_index_t **	out_link_index,
		loomc_result_t **	out_result )

Finishes a builder into a frozen immutable link index.

Parameters

builder	Builder to finish. The builder becomes finished after this call returns OK, whether the operation result succeeded or failed.
out_link_index	Receives one retained frozen index when the result state is succeeded.
out_result	Receives one retained result describing indexing outcome.

Returns: OK when a result was produced. Non-OK status means API or infrastructure failure prevented result production.

Ownership: Finishing does not consume builder; the caller still releases it with loomc_link_index_builder_release after the call returns. The caller owns out_link_index on successful result state and releases it with loomc_link_index_release. The caller owns out_result and releases it with loomc_result_release.

Error contract: Invalid Loom text, malformed bytecode, empty reserved slots, and unsupported source formats produce OK status plus a failed result with diagnostics.

◆ loomc_link_index_builder_release()

void loomc_link_index_builder_release ( loomc_link_index_builder_t * builder )

Releases a link-index builder.

Parameters

builder Builder to release. Passing NULL is allowed.

Thread safety: No other thread may be reserving, filling, or finishing builder.

◆ loomc_link_index_builder_reserve_source_slot()

loomc_status_t loomc_link_index_builder_reserve_source_slot	(	loomc_link_index_builder_t *	builder,
		const loomc_link_index_source_options_t *	options,
		loomc_link_index_source_slot_t *	out_slot )

Reserves a deterministic source slot.

Parameters

builder	Builder to mutate.
options	Provider options copied by this call, or NULL for defaults.
out_slot	Receives the reserved source slot.

Returns: OK when the slot was reserved.

Thread safety: Reserving slots requires exclusive access to builder.

◆ loomc_link_index_lookup_global()

bool loomc_link_index_lookup_global	(	const loomc_link_index_t *	link_index,
		loomc_string_view_t	name,
		loomc_link_index_symbol_t *	out_symbol )

Looks up the selected global symbol by name.

Parameters

link_index	Index to inspect.
name	Symbol name with or without a leading @.
out_symbol	Receives selected symbol metadata.

Returns: True when a global symbol named name was found.

◆ loomc_link_index_lookup_private()

bool loomc_link_index_lookup_private	(	const loomc_link_index_t *	link_index,
		const loomc_link_index_module_t *	module,
		loomc_string_view_t	name,
		loomc_link_index_symbol_t *	out_symbol )

Looks up a private symbol within an indexed module.

Parameters

link_index	Index to inspect.
module	Module metadata previously returned from this index.
name	Symbol name with or without a leading @.
out_symbol	Receives private symbol metadata.

Returns: True when a private symbol named name was found in module.

◆ loomc_link_index_module_at()

bool loomc_link_index_module_at	(	const loomc_link_index_t *	link_index,
		loomc_host_size_t	ordinal,
		loomc_link_index_module_t *	out_module )

Returns module metadata by ordinal.

Parameters

link_index	Index to inspect.
ordinal	Zero-based module ordinal.
out_module	Receives module metadata.

Returns: True when ordinal was valid.

◆ loomc_link_index_module_count()

loomc_host_size_t loomc_link_index_module_count ( const loomc_link_index_t * link_index )

Returns the number of modules in a frozen index.

Parameters

link_index Index to inspect.

Returns: Module count.

◆ loomc_link_index_next_global_duplicate()

bool loomc_link_index_next_global_duplicate	(	const loomc_link_index_t *	link_index,
		const loomc_link_index_symbol_t *	symbol,
		loomc_link_index_symbol_t *	out_symbol )

Returns the next duplicate global symbol for symbol.

Parameters

link_index	Index to inspect.
symbol	Symbol previously returned from this index.
out_symbol	Receives duplicate symbol metadata.

Returns: True when another duplicate exists.

◆ loomc_link_index_provider_at()

bool loomc_link_index_provider_at	(	const loomc_link_index_t *	link_index,
		loomc_host_size_t	ordinal,
		loomc_link_index_provider_t *	out_provider )

Returns provider metadata by ordinal.

Parameters

link_index	Index to inspect.
ordinal	Zero-based provider ordinal.
out_provider	Receives provider metadata.

Returns: True when ordinal was valid.

◆ loomc_link_index_provider_count()

loomc_host_size_t loomc_link_index_provider_count ( const loomc_link_index_t * link_index )

Returns the number of providers in a frozen index.

Parameters

link_index Index to inspect.

Returns: Provider count.

◆ loomc_link_index_release()

void loomc_link_index_release ( loomc_link_index_t * link_index )

Releases a frozen link index from one owner.

Parameters

link_index Link index to release. Passing NULL is allowed.

Thread safety: Retain/release operations for frozen indexes are intended to be safe from multiple threads. No mutation occurs after the index is frozen.

◆ loomc_link_index_retain()

void loomc_link_index_retain ( loomc_link_index_t * link_index )

Retains a frozen link index for another owner.

Parameters

link_index Link index to retain.

Thread safety: Retain/release operations for frozen indexes are intended to be safe from multiple threads.

◆ loomc_link_index_symbol_at()

bool loomc_link_index_symbol_at	(	const loomc_link_index_t *	link_index,
		loomc_host_size_t	ordinal,
		loomc_link_index_symbol_t *	out_symbol )

Returns symbol metadata by ordinal.

Parameters

link_index	Index to inspect.
ordinal	Zero-based symbol ordinal.
out_symbol	Receives symbol metadata.

Returns: True when ordinal was valid.

◆ loomc_link_index_symbol_count()

loomc_host_size_t loomc_link_index_symbol_count ( const loomc_link_index_t * link_index )

Returns the number of symbols in a frozen index.

Parameters

link_index Index to inspect.

Returns: Symbol count.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ loomc_link_index_builder_t

◆ loomc_link_index_t

Enumeration Type Documentation

◆ loomc_link_provider_kind_t

◆ loomc_link_provider_role_t

◆ loomc_link_symbol_flag_bits_t

◆ loomc_link_symbol_identity_t

◆ loomc_link_symbol_kind_t

Function Documentation

◆ loomc_link_index_builder_add_source()

◆ loomc_link_index_builder_create()

◆ loomc_link_index_builder_fill_source_slot()

◆ loomc_link_index_builder_finish()

◆ loomc_link_index_builder_release()

◆ loomc_link_index_builder_reserve_source_slot()

◆ loomc_link_index_lookup_global()

◆ loomc_link_index_lookup_private()

◆ loomc_link_index_module_at()

◆ loomc_link_index_module_count()

◆ loomc_link_index_next_global_duplicate()

◆ loomc_link_index_provider_at()

◆ loomc_link_index_provider_count()

◆ loomc_link_index_release()

◆ loomc_link_index_retain()

◆ loomc_link_index_symbol_at()

◆ loomc_link_index_symbol_count()