source.h File Reference

Immutable source handles used by parsing, indexing, linking, and compiling. More...

Go to the source code of this file.

Data Structures
struct	loomc_source_options_t
	Source creation options. More...
struct	loomc_source_load_options_t
	Source load options for host file and path constructors. More...

Typedefs
typedef struct loomc_source_t	loomc_source_t
	Immutable source handle.
typedef void(*	loomc_source_release_fn_t) (void *user_data, loomc_byte_span_t contents)
	Callback used to release externally owned source bytes.

Enumerations
enum	loomc_source_format_t { LOOMC_SOURCE_FORMAT_UNKNOWN = 0 , LOOMC_SOURCE_FORMAT_TEXT = 1 , LOOMC_SOURCE_FORMAT_BYTECODE = 2 }
	Source byte format. More...
enum	loomc_source_storage_t { LOOMC_SOURCE_STORAGE_BORROWED = 0 , LOOMC_SOURCE_STORAGE_COPY = 1 , LOOMC_SOURCE_STORAGE_EXTERNAL = 2 }
	Storage policy for source bytes. More...

Functions
loomc_status_t	loomc_source_create (const loomc_source_options_t *options, loomc_allocator_t allocator, loomc_source_t **out_source)
	Creates an immutable source handle.
loomc_status_t	loomc_source_create_from_file (FILE *file, const loomc_source_load_options_t *options, loomc_allocator_t allocator, loomc_source_t **out_source)
	Creates an immutable source by reading an open file.
loomc_status_t	loomc_source_create_from_path (loomc_string_view_t path, const loomc_source_load_options_t *options, loomc_allocator_t allocator, loomc_source_t **out_source)
	Creates an immutable source by reading a filesystem path.
void	loomc_source_retain (loomc_source_t *source)
	Retains source for another owner.
void	loomc_source_release (loomc_source_t *source)
	Releases source from one owner.
loomc_source_format_t	loomc_source_format (const loomc_source_t *source)
	Returns the source format.
loomc_string_view_t	loomc_source_identifier (const loomc_source_t *source)
	Returns the source identifier.
loomc_byte_span_t	loomc_source_contents (const loomc_source_t *source)
	Returns the source contents.

Detailed Description

Immutable source handles used by parsing, indexing, linking, and compiling.

Sources carry bytes plus stable identity. They are distinct from parsed modules and from output artifacts. Source identity is used for diagnostics, cache keys, and deterministic link-index provenance.

Example

Copy source bytes when the caller does not want source lifetime to depend on an external buffer:

const char* source_text = "...";
loomc_source_options_t options = {
    .type = LOOMC_STRUCTURE_TYPE_SOURCE_OPTIONS,
    .structure_size = sizeof(loomc_source_options_t),
    .format = LOOMC_SOURCE_FORMAT_TEXT,
    .identifier = loomc_make_cstring_view("generated.loom"),
    .contents = loomc_make_byte_span(source_text, strlen(source_text)),
    .storage = LOOMC_SOURCE_STORAGE_COPY,
};
 
loomc_source_t* source = NULL;
loomc_status_t status =
    loomc_source_create(&options, loomc_allocator_system(), &source);
if (!loomc_status_is_ok(status)) {
  return status;
}
 
// Use source from any worker thread after sharing or retaining it.
 
loomc_source_release(source);

Example

Load source bytes from a path and let the source own the loaded file buffer:

loomc_source_load_options_t options = {
    .type = LOOMC_STRUCTURE_TYPE_SOURCE_LOAD_OPTIONS,
    .structure_size = sizeof(loomc_source_load_options_t),
    .format = LOOMC_SOURCE_FORMAT_UNKNOWN,
};
 
loomc_source_t* source = NULL;
loomc_status_t status = loomc_source_create_from_path(
    loomc_make_cstring_view("profile.json"), &options,
    loomc_allocator_system(), &source);
if (!loomc_status_is_ok(status)) {
  return status;
}
 
// Pass source to a parser, importer, linker index builder, or compiler.
 
loomc_source_release(source);

Typedef Documentation

loomc_source_release_fn_t

typedef void(* loomc_source_release_fn_t) (void *user_data, loomc_byte_span_t contents)

Callback used to release externally owned source bytes.

Parameters

user_data	Caller-provided value from loomc_source_options_t.
contents	Source bytes being released.

Thread safety

The callback is invoked when the last source reference is released. Callers that share sources across threads must make the callback safe for whichever thread drops the final reference.

loomc_source_t

typedef struct loomc_source_t loomc_source_t

Immutable source handle.

Thread safety

Sources are immutable after creation. Retained source handles may be shared across threads.

Enumeration Type Documentation

loomc_source_format_t

enum loomc_source_format_t

Source byte format.

Enumerator
LOOMC_SOURCE_FORMAT_UNKNOWN	Source format is unknown and must be inferred by the consumer.
LOOMC_SOURCE_FORMAT_TEXT	Textual .loom source.
LOOMC_SOURCE_FORMAT_BYTECODE	Binary .loombc source.

loomc_source_storage_t

enum loomc_source_storage_t

Storage policy for source bytes.

Enumerator
LOOMC_SOURCE_STORAGE_BORROWED	Source bytes are borrowed from the caller for the lifetime of the source.
LOOMC_SOURCE_STORAGE_COPY	Source bytes are copied into storage owned by the source.
LOOMC_SOURCE_STORAGE_EXTERNAL	Source bytes are owned externally and released by a caller callback.

Function Documentation

loomc_source_contents()

loomc_byte_span_t loomc_source_contents

(

const loomc_source_t *

source

)

Returns the source contents.

Parameters

source

Source to inspect.

Returns

Borrowed byte span owned or referenced by source.

Lifetime

The returned span remains valid until source is released. For borrowed source storage, the caller-provided bytes must also remain alive.

loomc_source_create()

loomc_status_t loomc_source_create	(	const loomc_source_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_source_t **	out_source )

Creates an immutable source handle.

Parameters

options	Source format, identity, bytes, and storage policy.
allocator	Host allocator used for source-owned storage.
out_source	Receives one retained source on success.

Returns

OK when the source was created. Invalid argument is returned for malformed descriptors or impossible storage/release combinations.

Ownership

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

Lifetime

The source always copies options->identifier. Source contents are borrowed, copied, or externally released according to options->storage. Borrowed contents must outlive the source.

Thread safety

The returned source is immutable and may be shared across threads.

loomc_source_create_from_file()

loomc_status_t loomc_source_create_from_file	(	FILE *	file,
		const loomc_source_load_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_source_t **	out_source )

Creates an immutable source by reading an open file.

Parameters

file	Open file positioned at the first byte to read.
options	Source format and identity metadata, or NULL for defaults.
allocator	Host allocator used for source and byte storage.
out_source	Receives one retained source on success.

Returns

OK when all remaining file bytes were read into source-owned memory.

Ownership

The caller owns the returned reference and releases it with loomc_source_release. The caller still owns file and is responsible for closing it.

Lifetime

The returned source owns a copy of the bytes read from file; the file can be closed or reused after this call returns.

Thread safety

The returned source is immutable and may be shared across threads. This call performs ordinary C FILE* reads and does not synchronize access to file.

loomc_source_create_from_path()

loomc_status_t loomc_source_create_from_path	(	loomc_string_view_t	path,
		const loomc_source_load_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_source_t **	out_source )

Creates an immutable source by reading a filesystem path.

Parameters

path	Path to read. The path view need not be NUL-terminated.
options	Source format and identity metadata, or NULL for defaults.
allocator	Host allocator used for source and byte storage.
out_source	Receives one retained source on success.

Returns

OK when the path contents were read into source-owned memory.

Ownership

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

Lifetime

The returned source owns the loaded bytes and copies the source identifier. When options->identifier is empty, path is copied as the identifier.

Thread safety

The returned source is immutable and may be shared across threads.

loomc_source_format()

loomc_source_format_t loomc_source_format

(

const loomc_source_t *

source

)

Returns the source format.

Parameters

source

Source to inspect.

Returns

Format recorded when the source was created.

loomc_source_identifier()

loomc_string_view_t loomc_source_identifier

(

const loomc_source_t *

source

)

Returns the source identifier.

Parameters

source

Source to inspect.

Returns

Borrowed identifier view owned by source.

Lifetime

The returned view remains valid until source is released.

loomc_source_release()

void loomc_source_release

(

loomc_source_t *

source

)

Releases source from one owner.

Parameters

source

Source to release. Passing NULL is allowed.

Thread safety

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

loomc_source_retain()

void loomc_source_retain

(

loomc_source_t *

source

)

Retains source for another owner.

Parameters

source

Source to retain.

Thread safety

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