module.h File Reference

Opaque in-memory Loom modules. More...

Go to the source code of this file.

Data Structures
struct	loomc_module_function_t
	Function metadata view written into caller-provided storage. More...
struct	loomc_module_function_export_info_t
	Export metadata view written into caller-provided storage. More...
struct	loomc_module_function_query_options_t
	Module function query options. More...
struct	loomc_module_global_t
	Global metadata view written into caller-provided storage. More...
struct	loomc_module_global_query_options_t
	Module global query options. More...
struct	loomc_module_serialize_options_t
	Module serialization options. More...
struct	loomc_module_deserialize_options_t
	Module deserialization options. More...

Typedefs
typedef struct loomc_module_t	loomc_module_t
	Opaque parsed, linked, optimized, or lowered module.
typedef uint32_t	loomc_module_function_flags_t
	Bitmask of loomc_module_function_flag_bits_t values.
typedef uint32_t	loomc_module_function_export_flags_t
	Bitmask of loomc_module_function_export_flag_bits_t values.
typedef uint32_t	loomc_module_global_flags_t
	Bitmask of loomc_module_global_flag_bits_t values.

Enumerations
enum	loomc_module_function_kind_t {   LOOMC_MODULE_FUNCTION_KIND_UNKNOWN = 0 , LOOMC_MODULE_FUNCTION_KIND_FUNCTION = 1 , LOOMC_MODULE_FUNCTION_KIND_KERNEL = 2 , LOOMC_MODULE_FUNCTION_KIND_TARGET_FUNCTION = 3 ,   LOOMC_MODULE_FUNCTION_KIND_TARGET_KERNEL = 4 }
	Public function category reported from a module query. More...
enum	loomc_module_function_flag_bits_t { LOOMC_MODULE_FUNCTION_FLAG_PUBLIC = 1u << 0 , LOOMC_MODULE_FUNCTION_FLAG_HAS_EXPORT_INFO = 1u << 1 }
	Module function metadata flag bits. More...
enum	loomc_module_function_export_flag_bits_t { LOOMC_MODULE_FUNCTION_EXPORT_FLAG_HAS_SYMBOL = 1u << 0 }
	Export metadata flag bits. More...
enum	loomc_module_global_kind_t { LOOMC_MODULE_GLOBAL_KIND_UNKNOWN = 0 , LOOMC_MODULE_GLOBAL_KIND_CONSTANT = 1 , LOOMC_MODULE_GLOBAL_KIND_VARIABLE = 2 }
	Public global category reported from a module query. More...
enum	loomc_module_global_flag_bits_t { LOOMC_MODULE_GLOBAL_FLAG_PUBLIC = 1u << 0 }
	Module global metadata flag bits. More...
enum	loomc_module_text_presentation_t { LOOMC_MODULE_TEXT_PRESENTATION_DEFAULT = 0 , LOOMC_MODULE_TEXT_PRESENTATION_GENERIC = 1 , LOOMC_MODULE_TEXT_PRESENTATION_LOW_ASM = 2 }
	Text presentation policy used when serializing .loom text. More...

Functions
void	loomc_module_retain (loomc_module_t *module)
	Retains an opaque module for another owner.
void	loomc_module_release (loomc_module_t *module)
	Releases an opaque module from one owner.
loomc_status_t	loomc_module_clone (const loomc_module_t *source_module, loomc_workspace_t *workspace, loomc_allocator_t allocator, loomc_module_t **out_module)
	Clones a module into workspace-backed mutable storage.
loomc_status_t	loomc_module_query_functions (const loomc_module_t *module, const loomc_module_function_query_options_t *options, loomc_allocator_t allocator, loomc_host_size_t function_capacity, loomc_module_function_t *out_functions, loomc_host_size_t *out_function_count, loomc_result_t **out_result)
	Queries function metadata from a module.
loomc_status_t	loomc_module_query_globals (const loomc_module_t *module, const loomc_module_global_query_options_t *options, loomc_allocator_t allocator, loomc_host_size_t global_capacity, loomc_module_global_t *out_globals, loomc_host_size_t *out_global_count, loomc_result_t **out_result)
	Queries global metadata from a module.
bool	loomc_module_try_get_function_at (const loomc_module_t *module, loomc_host_size_t function_ordinal, loomc_module_function_t *out_function)
	Tries to get function metadata by public function ordinal without allocating a status.
loomc_status_t	loomc_module_get_function_at (const loomc_module_t *module, loomc_host_size_t function_ordinal, loomc_module_function_t *out_function)
	Gets function metadata by public function ordinal.
bool	loomc_module_try_lookup_function (const loomc_module_t *module, loomc_string_view_t symbol_name, loomc_module_function_t *out_function)
	Looks up one function by symbol name without allocating a status.
loomc_status_t	loomc_module_lookup_function (const loomc_module_t *module, loomc_string_view_t symbol_name, loomc_module_function_t *out_function)
	Looks up one function by symbol name.
bool	loomc_module_try_get_global_at (const loomc_module_t *module, loomc_host_size_t global_ordinal, loomc_module_global_t *out_global)
	Tries to get global metadata by global ordinal without allocating a status.
loomc_status_t	loomc_module_get_global_at (const loomc_module_t *module, loomc_host_size_t global_ordinal, loomc_module_global_t *out_global)
	Gets global metadata by global ordinal.
bool	loomc_module_try_lookup_global (const loomc_module_t *module, loomc_string_view_t symbol_name, loomc_module_global_t *out_global)
	Looks up one global by symbol name without allocating a status.
loomc_status_t	loomc_module_lookup_global (const loomc_module_t *module, loomc_string_view_t symbol_name, loomc_module_global_t *out_global)
	Looks up one global by symbol name.
bool	loomc_module_function_try_get_export_info_at (const loomc_module_t *module, loomc_host_size_t function_ordinal, loomc_module_function_export_info_t *out_info)
	Tries to get export metadata by public function ordinal without allocating a status.
loomc_status_t	loomc_module_function_get_export_info_at (const loomc_module_t *module, loomc_host_size_t function_ordinal, loomc_module_function_export_info_t *out_info)
	Gets export metadata by public function ordinal.
bool	loomc_module_function_try_get_export_info (const loomc_module_t *module, const loomc_module_function_t *function, loomc_module_function_export_info_t *out_info)
	Tries to get export metadata for a function without allocating a status.
loomc_status_t	loomc_module_function_get_export_info (const loomc_module_t *module, const loomc_module_function_t *function, loomc_module_function_export_info_t *out_info)
	Gets export metadata for a function.
loomc_status_t	loomc_module_serialize_to_source (const loomc_module_t *module, const loomc_module_serialize_options_t *options, loomc_allocator_t allocator, loomc_source_t **out_source)
	Serializes a module into an immutable source handle.
loomc_status_t	loomc_module_serialize_to_file (const loomc_module_t *module, const loomc_module_serialize_options_t *options, FILE *file)
	Serializes a module to an open C FILE*.
loomc_status_t	loomc_module_serialize_to_path (const loomc_module_t *module, const loomc_module_serialize_options_t *options, loomc_string_view_t path, loomc_allocator_t allocator)
	Serializes a module to a filesystem path.
loomc_status_t	loomc_module_deserialize_from_source (loomc_context_t *context, loomc_workspace_t *workspace, const loomc_source_t *source, const loomc_module_deserialize_options_t *options, loomc_allocator_t allocator, loomc_module_t **out_module, loomc_result_t **out_result)
	Deserializes an immutable source handle into an owned mutable module.
loomc_status_t	loomc_module_deserialize_from_file (loomc_context_t *context, loomc_workspace_t *workspace, FILE *file, const loomc_module_deserialize_options_t *options, loomc_allocator_t allocator, loomc_module_t **out_module, loomc_result_t **out_result)
	Deserializes bytes from an open C FILE* into a module.
loomc_status_t	loomc_module_deserialize_from_path (loomc_context_t *context, loomc_workspace_t *workspace, loomc_string_view_t path, const loomc_module_deserialize_options_t *options, loomc_allocator_t allocator, loomc_module_t **out_module, loomc_result_t **out_result)
	Deserializes bytes from a filesystem path into a module.

Detailed Description

Opaque in-memory Loom modules.

Modules are the typed handoff between parsing, linking, optimization, and compilation. They let embedders compose API operations without printing and reparsing .loom text on the hot path. Serialization is the boundary that turns a module back into text or bytecode bytes for storage, display, cache keys, or handoff to systems that consume sources. Deserialization is the inverse boundary that turns text or bytecode bytes into a mutable module handle allocated from a caller-provided workspace.

Example

Serialize a linked module back to an immutable source handle:

loomc_module_serialize_options_t options = {
    .type = LOOMC_STRUCTURE_TYPE_MODULE_SERIALIZE_OPTIONS,
    .structure_size = sizeof(loomc_module_serialize_options_t),
    .format = LOOMC_SOURCE_FORMAT_BYTECODE,
    .identifier = loomc_make_cstring_view("linked.loombc"),
};
loomc_source_t* serialized = NULL;
loomc_status_t status = loomc_module_serialize_to_source(
    module, &options, loomc_allocator_system(), &serialized);
if (!loomc_status_is_ok(status)) {
  return status;
}
 
// Reuse serialized as ordinary source input, cache it, or inspect its
bytes.
 
loomc_source_release(serialized);

Example

Deserialize a source handle into a module and inspect the result:

loomc_module_t* module = NULL;
loomc_result_t* result = NULL;
loomc_status_t status = loomc_module_deserialize_from_source(
    context, workspace, serialized, NULL, loomc_allocator_system(), &module,
    &result);
if (!loomc_status_is_ok(status)) {
  return status;
}
if (!loomc_result_succeeded(result)) {
  // Diagnostics are available through loomc_result_diagnostic_at.
}
 
loomc_result_release(result);
loomc_module_release(module);

Typedef Documentation

loomc_module_t

typedef struct loomc_module_t loomc_module_t

Opaque parsed, linked, optimized, or lowered module.

Modules use arena storage from the workspace that created, linked, cloned, or deserialized them. Releasing a module returns its active arena blocks to that workspace. A module retains the workspace, so release ordering is memory-safe, but keeping modules live across loomc_workspace_trim keeps their storage live too.

Thread safety

Retain/release operations are safe from multiple threads. Module contents are not internally synchronized. Read-only operations such as serialization may run concurrently with other read-only operations when the caller guarantees that no mutating module operation is active. Mutating operations such as compiling a module require exclusive access to that module handle.

Enumeration Type Documentation

loomc_module_function_export_flag_bits_t

enum loomc_module_function_export_flag_bits_t

Export metadata flag bits.

Enumerator
LOOMC_MODULE_FUNCTION_EXPORT_FLAG_HAS_SYMBOL	loomc_module_function_export_info_t::export_symbol is present.

loomc_module_function_flag_bits_t

enum loomc_module_function_flag_bits_t

Module function metadata flag bits.

Enumerator
LOOMC_MODULE_FUNCTION_FLAG_PUBLIC	Function symbol is visible outside the module for linking.
LOOMC_MODULE_FUNCTION_FLAG_HAS_EXPORT_INFO	loomc_module_function_try_get_export_info can return export metadata.

loomc_module_function_kind_t

enum loomc_module_function_kind_t

Public function category reported from a module query.

Enumerator
LOOMC_MODULE_FUNCTION_KIND_UNKNOWN	No specific function kind was requested or reported.
LOOMC_MODULE_FUNCTION_KIND_FUNCTION	Source-level func.def function definition.
LOOMC_MODULE_FUNCTION_KIND_KERNEL	Source-level kernel.def dispatchable kernel definition.
LOOMC_MODULE_FUNCTION_KIND_TARGET_FUNCTION	Target-bound function definition produced by lowering.
LOOMC_MODULE_FUNCTION_KIND_TARGET_KERNEL	Target-bound dispatchable kernel entry produced by lowering.

loomc_module_global_flag_bits_t

enum loomc_module_global_flag_bits_t

Module global metadata flag bits.

Enumerator
LOOMC_MODULE_GLOBAL_FLAG_PUBLIC	Global symbol is visible outside the module for linking.

loomc_module_global_kind_t

enum loomc_module_global_kind_t

Public global category reported from a module query.

Enumerator
LOOMC_MODULE_GLOBAL_KIND_UNKNOWN	No specific global kind was requested or reported.
LOOMC_MODULE_GLOBAL_KIND_CONSTANT	Immutable global.constant definition.
LOOMC_MODULE_GLOBAL_KIND_VARIABLE	Mutable global.variable definition.

loomc_module_text_presentation_t

enum loomc_module_text_presentation_t

Text presentation policy used when serializing .loom text.

Enumerator
LOOMC_MODULE_TEXT_PRESENTATION_DEFAULT	Prefer target-low assembly syntax using each function's representation contract, with canonical text as a lossless fallback.
LOOMC_MODULE_TEXT_PRESENTATION_GENERIC	Force canonical text with descriptor-backed target-low operations printed as ordinary low.op<...> operations.
LOOMC_MODULE_TEXT_PRESENTATION_LOW_ASM	Require descriptor-backed target-low assembly syntax for every self-describing target-low function. Serialization fails when a function has no lossless assembly spelling for its representation contract.

Function Documentation

loomc_module_clone()

loomc_status_t loomc_module_clone	(	const loomc_module_t *	source_module,
		loomc_workspace_t *	workspace,
		loomc_allocator_t	allocator,
		loomc_module_t **	out_module )

Clones a module into workspace-backed mutable storage.

Parameters

source_module	Module to clone. The source is read-only during this operation.
workspace	Workspace used to allocate the cloned module's IR storage.
allocator	Host allocator used for the returned module handle.
out_module	Receives the cloned module on success.

Returns

OK when the clone succeeded.

Ownership

The caller owns the returned module and releases it with loomc_module_release.

Lifetime

The cloned module retains workspace and returns its arena blocks when the module is released. The clone does not borrow from source_module; both modules may be mutated independently after this call returns. When a prior compilation retained resolved function targets outside the source IR, the clone materializes those targets into ordinary definitions and function target references. The clone needs no invocation-local compiler facts.

Thread safety

Cloning reads source_module and mutates workspace. Concurrent clones of the same source are valid when no thread is mutating that source module. Distinct workspaces may be used concurrently.

loomc_module_deserialize_from_file()

loomc_status_t loomc_module_deserialize_from_file	(	loomc_context_t *	context,
		loomc_workspace_t *	workspace,
		FILE *	file,
		const loomc_module_deserialize_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_module_t **	out_module,
		loomc_result_t **	out_result )

Deserializes bytes from an open C FILE* into a module.

Parameters

context	Context used to resolve Loom dialect and bytecode metadata.
workspace	Workspace used to allocate module IR storage.
file	Open readable file handle. Bytes are read from the current file position to EOF.
options	Deserialization options. NULL infers format from bytes.
allocator	Host allocator used for module handle storage and temporary input bytes.
out_module	Receives a retained module when the result succeeds. Receives NULL when the result fails.
out_result	Receives a retained result for the operation.

Returns

OK when deserialization ran to a result. Non-OK statuses represent API misuse, file read failures, or infrastructure failures before a result could be produced.

Ownership

The caller retains ownership of file; this function does not close it. The returned module retains workspace.

loomc_module_deserialize_from_path()

loomc_status_t loomc_module_deserialize_from_path	(	loomc_context_t *	context,
		loomc_workspace_t *	workspace,
		loomc_string_view_t	path,
		const loomc_module_deserialize_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_module_t **	out_module,
		loomc_result_t **	out_result )

Deserializes bytes from a filesystem path into a module.

Parameters

context	Context used to resolve Loom dialect and bytecode metadata.
workspace	Workspace used to allocate module IR storage.
path	Input file path. The path is a borrowed byte view and does not need to be NUL-terminated.
options	Deserialization options. NULL infers format from bytes.
allocator	Host allocator used for module handle storage and temporary input bytes.
out_module	Receives a retained module when the result succeeds. Receives NULL when the result fails.
out_result	Receives a retained result for the operation.

Returns

OK when deserialization ran to a result. Non-OK statuses represent API misuse, file read failures, or infrastructure failures before a result could be produced.

loomc_module_deserialize_from_source()

loomc_status_t loomc_module_deserialize_from_source	(	loomc_context_t *	context,
		loomc_workspace_t *	workspace,
		const loomc_source_t *	source,
		const loomc_module_deserialize_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_module_t **	out_module,
		loomc_result_t **	out_result )

Deserializes an immutable source handle into an owned mutable module.

Parameters

context	Context used to resolve Loom dialect and bytecode metadata.
workspace	Workspace used to allocate module IR storage.
source	Source bytes to deserialize.
options	Deserialization options. NULL infers format from source.
allocator	Host allocator used for module handle storage.
out_module	Receives a retained module when the result succeeds. Receives NULL when the result fails.
out_result	Receives a retained result for the operation.

Returns

OK when deserialization 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 returned module retains workspace. The caller always owns out_result on an OK return and releases it with loomc_result_release.

Lifetime

Returned modules and results do not borrow from source. Diagnostics retain source when they reference it. Later module operations may mutate the returned module in place. Releasing the module returns its arena blocks to workspace; keeping it live across loomc_workspace_trim keeps those blocks live.

loomc_module_function_get_export_info()

loomc_status_t loomc_module_function_get_export_info	(	const loomc_module_t *	module,
		const loomc_module_function_t *	function,
		loomc_module_function_export_info_t *	out_info )

Gets export metadata for a function.

Parameters

module	Module that produced function.
function	Function metadata from module.
out_info	Receives export metadata.

Returns

OK when export metadata is available, NOT_FOUND when function has no export metadata, or another non-OK status for API misuse.

loomc_module_function_get_export_info_at()

loomc_status_t loomc_module_function_get_export_info_at	(	const loomc_module_t *	module,
		loomc_host_size_t	function_ordinal,
		loomc_module_function_export_info_t *	out_info )

Gets export metadata by public function ordinal.

Parameters

module	Module to inspect.
function_ordinal	Ordinal in the module's unfiltered function metadata sequence.
out_info	Receives export metadata.

Returns

OK when export metadata is available, NOT_FOUND when the ordinal does not name a function with export metadata, or another non-OK status for API misuse.

loomc_module_function_try_get_export_info()

bool loomc_module_function_try_get_export_info	(	const loomc_module_t *	module,
		const loomc_module_function_t *	function,
		loomc_module_function_export_info_t *	out_info )

Tries to get export metadata for a function without allocating a status.

Parameters

module	Module that produced function.
function	Function metadata from module.
out_info	Receives export metadata when available.

Returns

True when function has export metadata.

loomc_module_function_try_get_export_info_at()

bool loomc_module_function_try_get_export_info_at	(	const loomc_module_t *	module,
		loomc_host_size_t	function_ordinal,
		loomc_module_function_export_info_t *	out_info )

Tries to get export metadata by public function ordinal without allocating a status.

Parameters

module	Module to inspect.
function_ordinal	Ordinal in the module's unfiltered function metadata sequence.
out_info	Receives export metadata when available.

Returns

True when function_ordinal names a function with export metadata.

loomc_module_get_function_at()

loomc_status_t loomc_module_get_function_at	(	const loomc_module_t *	module,
		loomc_host_size_t	function_ordinal,
		loomc_module_function_t *	out_function )

Gets function metadata by public function ordinal.

Parameters

module	Module to inspect.
function_ordinal	Ordinal in the module's unfiltered function metadata sequence.
out_function	Receives function metadata.

Returns

OK when the ordinal names a supported function, NOT_FOUND when it does not, or another non-OK status for API misuse.

loomc_module_get_global_at()

loomc_status_t loomc_module_get_global_at	(	const loomc_module_t *	module,
		loomc_host_size_t	global_ordinal,
		loomc_module_global_t *	out_global )

Gets global metadata by global ordinal.

Parameters

module	Module to inspect.
global_ordinal	Ordinal in the module's unfiltered global metadata sequence.
out_global	Receives global metadata.

Returns

OK when the ordinal names a supported global, NOT_FOUND when it does not, or another non-OK status for API misuse.

loomc_module_lookup_function()

loomc_status_t loomc_module_lookup_function	(	const loomc_module_t *	module,
		loomc_string_view_t	symbol_name,
		loomc_module_function_t *	out_function )

Looks up one function by symbol name.

Parameters

module	Module to inspect.
symbol_name	Function symbol name, with or without a leading @.
out_function	Receives function metadata when the lookup succeeds.

Returns

OK when symbol_name names a supported function, NOT_FOUND when it does not, or another non-OK status for API misuse.

loomc_module_lookup_global()

loomc_status_t loomc_module_lookup_global	(	const loomc_module_t *	module,
		loomc_string_view_t	symbol_name,
		loomc_module_global_t *	out_global )

Looks up one global by symbol name.

Parameters

module	Module to inspect.
symbol_name	Global symbol name, with or without a leading @.
out_global	Receives global metadata when the lookup succeeds.

Returns

OK when symbol_name names a supported global, NOT_FOUND when it does not, or another non-OK status for API misuse.

loomc_module_query_functions()

loomc_status_t loomc_module_query_functions	(	const loomc_module_t *	module,
		const loomc_module_function_query_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_host_size_t	function_capacity,
		loomc_module_function_t *	out_functions,
		loomc_host_size_t *	out_function_count,
		loomc_result_t **	out_result )

Queries function metadata from a module.

Parameters

module	Module to inspect.
options	Query options. NULL enumerates all supported function kinds.
allocator	Host allocator used for the returned result.
function_capacity	Number of entries available in out_functions.
out_functions	Caller-owned output storage. May be NULL only when function_capacity is zero.
out_function_count	Receives the total number of matching functions, which may be larger than function_capacity.
out_result	Receives a retained result for the query.

Returns

OK when the query ran to a result. Non-OK statuses represent API misuse or infrastructure failures before a result could be produced.

Ownership

The caller owns out_functions storage. The caller always owns out_result on an OK return and releases it with loomc_result_release.

Lifetime

Function string views borrow from module. Returned views and function ordinals remain valid until the module is released or mutated. Follow-up metadata queries must use the same module that produced the function views.

Thread safety

Function queries are read-only with respect to module. Concurrent queries of the same module are valid when the caller guarantees that no mutating module operation is active.

Example

Enumerate exported source kernels:

static loomc_status_t list_exported_kernels(loomc_module_t* module) {
  loomc_allocator_t allocator = loomc_allocator_system();
  loomc_module_function_query_options_t options = {
      .type = LOOMC_STRUCTURE_TYPE_MODULE_FUNCTION_QUERY_OPTIONS,
      .structure_size = sizeof(loomc_module_function_query_options_t),
      .kind = LOOMC_MODULE_FUNCTION_KIND_KERNEL,
  };
 
  loomc_module_function_t* functions = NULL;
  loomc_host_size_t function_count = 0;
  loomc_result_t* result = NULL;
  loomc_status_t status = loomc_module_query_functions(
      module, &options, allocator, 0, NULL, &function_count, &result);
 
  if (loomc_status_is_ok(status) && loomc_result_succeeded(result) &&
      function_count != 0) {
    loomc_result_release(result);
    result = NULL;
    status = loomc_allocator_malloc(
        allocator, function_count * sizeof(*functions), (void**)&functions);
  }
  if (loomc_status_is_ok(status) && functions != NULL) {
    status = loomc_module_query_functions(module, &options, allocator,
                                          function_count, functions,
                                          &function_count, &result);
  }
  if (loomc_status_is_ok(status) && result != NULL &&
      loomc_result_succeeded(result)) {
    for (loomc_host_size_t i = 0; i < function_count; ++i) {
      loomc_module_function_export_info_t export_info;
      if (loomc_module_function_try_get_export_info_at(
              module, functions[i].function_ordinal, &export_info)) {
        register_export(functions[i].symbol_name,
                        export_info.export_symbol);
      }
    }
  }
 
  loomc_allocator_free(allocator, functions);
  loomc_result_release(result);
  return status;
}

loomc_module_query_globals()

loomc_status_t loomc_module_query_globals	(	const loomc_module_t *	module,
		const loomc_module_global_query_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_host_size_t	global_capacity,
		loomc_module_global_t *	out_globals,
		loomc_host_size_t *	out_global_count,
		loomc_result_t **	out_result )

Queries global metadata from a module.

Parameters

module	Module to inspect.
options	Query options. NULL enumerates all supported global kinds.
allocator	Host allocator used for the returned result.
global_capacity	Number of entries available in out_globals.
out_globals	Caller-owned output storage. May be NULL only when global_capacity is zero.
out_global_count	Receives the total number of matching globals, which may be larger than global_capacity.
out_result	Receives a retained result for the query.

Returns

OK when the query ran to a result. Non-OK statuses represent API misuse or infrastructure failures before a result could be produced.

Ownership

The caller owns out_globals storage. The caller always owns out_result on an OK return and releases it with loomc_result_release.

Lifetime

Global string views borrow from module. Returned views and global ordinals remain valid until the module is released or mutated. Follow-up metadata queries must use the same module that produced the global views.

Thread safety

Global queries are read-only with respect to module. Concurrent queries of the same module are valid when the caller guarantees that no mutating module operation is active.

Example

Find mutable globals that an embedding runtime may need to allocate:

static loomc_status_t list_mutable_globals(loomc_module_t* module) {
  loomc_allocator_t allocator = loomc_allocator_system();
  loomc_module_global_query_options_t options = {
      .type = LOOMC_STRUCTURE_TYPE_MODULE_GLOBAL_QUERY_OPTIONS,
      .structure_size = sizeof(loomc_module_global_query_options_t),
      .kind = LOOMC_MODULE_GLOBAL_KIND_VARIABLE,
  };
 
  loomc_module_global_t* globals = NULL;
  loomc_host_size_t global_count = 0;
  loomc_result_t* result = NULL;
  loomc_status_t status = loomc_module_query_globals(
      module, &options, allocator, 0, NULL, &global_count, &result);
 
  if (loomc_status_is_ok(status) && loomc_result_succeeded(result) &&
      global_count != 0) {
    loomc_result_release(result);
    result = NULL;
    status = loomc_allocator_malloc(
        allocator, global_count * sizeof(*globals), (void**)&globals);
  }
  if (loomc_status_is_ok(status) && globals != NULL) {
    status = loomc_module_query_globals(module, &options, allocator,
                                        global_count, globals,
                                        &global_count, &result);
  }
  if (loomc_status_is_ok(status) && result != NULL &&
      loomc_result_succeeded(result)) {
    for (loomc_host_size_t i = 0; i < global_count; ++i) {
      allocate_global_storage(globals[i].symbol_name);
    }
  }
 
  loomc_allocator_free(allocator, globals);
  loomc_result_release(result);
  return status;
}

loomc_module_release()

void loomc_module_release

(

loomc_module_t *

module

)

Releases an opaque module from one owner.

Parameters

module

Module to release. Passing NULL is allowed.

Thread safety

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

loomc_module_retain()

void loomc_module_retain

(

loomc_module_t *

module

)

Retains an opaque module for another owner.

Parameters

module

Module to retain.

Thread safety

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

loomc_module_serialize_to_file()

loomc_status_t loomc_module_serialize_to_file	(	const loomc_module_t *	module,
		const loomc_module_serialize_options_t *	options,
		FILE *	file )

Serializes a module to an open C FILE*.

Parameters

module	Module to serialize.
options	Serialization options. NULL selects textual .loom.
file	Open writable file handle, such as stdout.

Returns

OK when serialization succeeded.

Ownership

The caller retains ownership of file; this function does not close it. Target projection completes before any bytes are written to file.

loomc_module_serialize_to_path()

loomc_status_t loomc_module_serialize_to_path	(	const loomc_module_t *	module,
		const loomc_module_serialize_options_t *	options,
		loomc_string_view_t	path,
		loomc_allocator_t	allocator )

Serializes a module to a filesystem path.

Parameters

module	Module to serialize.
options	Serialization options. NULL selects textual .loom.
path	Output file path. The path is a borrowed byte view and does not need to be NUL-terminated.
allocator	Host allocator used for transient file path/stream storage.

Returns

OK when serialization succeeded.

Exact target projection completes before the output path is opened, so a projection failure does not create or truncate the path.

loomc_module_serialize_to_source()

loomc_status_t loomc_module_serialize_to_source	(	const loomc_module_t *	module,
		const loomc_module_serialize_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_source_t **	out_source )

Serializes a module into an immutable source handle.

Parameters

module	Module to serialize.
options	Serialization options. NULL selects textual .loom.
allocator	Host allocator used for source-owned storage.
out_source	Receives one retained source on success.

Returns

OK when serialization succeeded.

Ownership

The caller owns the returned source and releases it with loomc_source_release. Serialized bytes are owned by that source and remain valid until the source is released.

Resolved Targets

When a prior compilation retained resolved function targets outside the module IR, serialization first projects them into a derived module without mutating the source. The resulting source is self-contained and can be deserialized in a fresh context without the original profiles. Serialization fails when an exact target definition cannot be materialized; it never silently emits the less-specific authored target.

Thread safety

Serialization is read-only with respect to module. Concurrent serialization of the same module is valid when the caller guarantees that no mutating operation is active.

loomc_module_try_get_function_at()

bool loomc_module_try_get_function_at	(	const loomc_module_t *	module,
		loomc_host_size_t	function_ordinal,
		loomc_module_function_t *	out_function )

Tries to get function metadata by public function ordinal without allocating a status.

Parameters

module	Module to inspect.
function_ordinal	Ordinal in the module's unfiltered function metadata sequence.
out_function	Receives function metadata when the ordinal names a supported function.

Returns

True when function_ordinal names a supported function.

loomc_module_try_get_global_at()

bool loomc_module_try_get_global_at	(	const loomc_module_t *	module,
		loomc_host_size_t	global_ordinal,
		loomc_module_global_t *	out_global )

Tries to get global metadata by global ordinal without allocating a status.

Parameters

module	Module to inspect.
global_ordinal	Ordinal in the module's unfiltered global metadata sequence.
out_global	Receives global metadata when the ordinal names a supported global.

Returns

True when global_ordinal names a supported global.

loomc_module_try_lookup_function()

bool loomc_module_try_lookup_function	(	const loomc_module_t *	module,
		loomc_string_view_t	symbol_name,
		loomc_module_function_t *	out_function )

Looks up one function by symbol name without allocating a status.

Parameters

module	Module to inspect.
symbol_name	Function symbol name, with or without a leading @.
out_function	Receives function metadata when the lookup succeeds.

Returns

True when symbol_name names a supported function.

loomc_module_try_lookup_global()

bool loomc_module_try_lookup_global	(	const loomc_module_t *	module,
		loomc_string_view_t	symbol_name,
		loomc_module_global_t *	out_global )

Looks up one global by symbol name without allocating a status.

Parameters

module	Module to inspect.
symbol_name	Global symbol name, with or without a leading @.
out_global	Receives global metadata when the lookup succeeds.

Returns

True when symbol_name names a supported global.