context.h File Reference

Reusable Loom API context. More...

Go to the source code of this file.

Data Structures
struct	loomc_context_options_t
	Context creation options. More...

Typedefs
typedef struct loomc_context_t	loomc_context_t
	Immutable Loom API context.

Enumerations
enum	loomc_source_retention_t { LOOMC_SOURCE_RETENTION_EXACT = 0 , LOOMC_SOURCE_RETENTION_METADATA_ONLY = 1 }
	Retention policy for source contents used to enrich diagnostics. More...

Functions
loomc_status_t	loomc_context_create (const loomc_context_options_t *options, loomc_allocator_t allocator, loomc_context_t **out_context)
	Creates a reusable Loom API context.
void	loomc_context_retain (loomc_context_t *context)
	Retains context for another owner.
void	loomc_context_release (loomc_context_t *context)
	Releases context from one owner.

Detailed Description

Reusable Loom API context.

A context owns process-local Loom language registration state used by parsing, bytecode indexing, linking, and compilation. Embedders normally create one context for a process or toolchain instance and share it with prepared linkers, compilers, and link-index builders.

Example

Create a context once, then reuse it while building persistent indexes:

loomc_context_t* context = NULL;
loomc_status_t status =
    loomc_context_create(NULL, loomc_allocator_system(), &context);
if (!loomc_status_is_ok(status)) {
  return status;
}
 
// Use context to create link-index builders, linkers, and compilers.
 
loomc_context_release(context);

Metadata-only source retention

Long-lived compilers that report structured diagnostics without rendering source excerpts can omit authored source bytes from retained modules and results:

loomc_context_options_t options = {
    .type = LOOMC_STRUCTURE_TYPE_CONTEXT_OPTIONS,
    .structure_size = sizeof(loomc_context_options_t),
    .source_retention = LOOMC_SOURCE_RETENTION_METADATA_ONLY,
};
loomc_context_t* context = NULL;
loomc_status_t status = loomc_context_create(
    &options, loomc_allocator_system(), &context);

Typedef Documentation

loomc_context_t

typedef struct loomc_context_t loomc_context_t

Immutable Loom API context.

Thread safety

Contexts are immutable after creation and may be shared across threads. Operations that need mutable source-location tables serialize that mutation through their owning builder or invocation object rather than exposing it on the context API.

Enumeration Type Documentation

loomc_source_retention_t

enum loomc_source_retention_t

Retention policy for source contents used to enrich diagnostics.

Enumerator
LOOMC_SOURCE_RETENTION_EXACT	Retain exact source contents referenced by admitted IR. This is the default and allows later compiler diagnostics to render source excerpts.
LOOMC_SOURCE_RETENTION_METADATA_ONLY	Retain source identifiers and available coordinates without source contents. Structured diagnostics remain available without keeping authored files live with modules, results, or text link indexes.

Function Documentation

loomc_context_create()

loomc_status_t loomc_context_create	(	const loomc_context_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_context_t **	out_context )

Creates a reusable Loom API context.

Parameters

options	Context options, or NULL for defaults.
allocator	Host allocator used for context-owned storage.
out_context	Receives one retained context on success.

Returns

OK when the context was created.

Ownership

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

Thread safety

The returned context is immutable and may be shared across prepared tools and worker threads.

loomc_context_release()

void loomc_context_release

(

loomc_context_t *

context

)

Releases context from one owner.

Parameters

context

Context to release. Passing NULL is allowed.

Thread safety

Retain/release operations are safe to perform from multiple threads. The context is destroyed when the final reference is released.

loomc_context_retain()

void loomc_context_retain

(

loomc_context_t *

context

)

Retains context for another owner.

Parameters

context

Context to retain.

Thread safety

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