program.h File Reference

Portable command-program products and independent kernel requests. More...

Go to the source code of this file.

Data Structures
struct	loomc_cmd_program_product_options_t
	Command-product construction options. More...
struct	loomc_cmd_program_request_options_t
	Command-product options for an ordinary bytecode request. More...
struct	loomc_cmd_program_module_options_t
	Command-product options for one invocation-local materialized module. More...
struct	loomc_cmd_program_t
	One serialized command root and its executable-entry projection. More...
struct	loomc_cmd_entry_requirement_t
	One product-wide executable-entry binding requirement. More...

Macros
#define	LOOMC_ARTIFACT_FORMAT_CMD_PROGRAM   "loom-command"
	Stable format name for serialized portable command-program bytes.
#define	LOOMC_ARTIFACT_FORMAT_CMD_PROGRAM_LISTING   "cmd-assembly"
	Stable format name for lowered command-program assembly text.

Typedefs
typedef uint32_t	loomc_cmd_program_product_flags_t
	Bitmask of loomc_cmd_program_product_flag_bits_t values.

Enumerations
enum	loomc_cmd_program_product_flag_bits_t { LOOMC_CMD_PROGRAM_PRODUCT_FLAG_INCLUDE_INPUT_EXPORTS = 1u << 0 }
	Command-product operation flag bits. More...

Functions
loomc_status_t	loomc_cmd_program_product_build (loomc_workspace_t *workspace, const loomc_cmd_program_product_options_t *options, loomc_allocator_t allocator, loomc_product_t **out_product, loomc_result_t **out_result)
	Builds portable command programs and optional kernel source requests.
loomc_status_t	loomc_cmd_program_product_build_request (loomc_context_t *context, loomc_workspace_t *workspace, const loomc_request_t *request, const loomc_cmd_program_request_options_t *options, loomc_allocator_t allocator, loomc_product_t **out_product, loomc_result_t **out_result)
	Builds portable command programs from an ordinary bytecode request.
loomc_status_t	loomc_cmd_program_product_build_module (loomc_workspace_t *workspace, const loomc_module_t *module, const loomc_cmd_program_module_options_t *options, loomc_allocator_t allocator, loomc_product_t **out_product, loomc_result_t **out_result)
	Builds portable command programs from a materialized module.
const loomc_product_descriptor_t *	loomc_cmd_program_product_descriptor (void)
	Returns the process-local command-product descriptor.
loomc_host_size_t	loomc_cmd_program_product_program_count (const loomc_product_t *product)
	Returns the number of serialized command roots in product.
bool	loomc_cmd_program_product_program_at (const loomc_product_t *product, loomc_host_size_t ordinal, loomc_cmd_program_t *out_program)
	Returns serialized command-root metadata by product-local ordinal.
loomc_host_size_t	loomc_cmd_program_product_entry_requirement_count (const loomc_product_t *product)
	Returns the number of product-wide executable-entry requirements.
bool	loomc_cmd_program_product_entry_requirement_at (const loomc_product_t *product, loomc_host_size_t ordinal, loomc_cmd_entry_requirement_t *out_requirement)
	Returns an executable-entry requirement by product-local ordinal.

Detailed Description

Portable command-program products and independent kernel requests.

Command product construction selects command roots from a reusable frozen link index, lowers their host-side orchestration to portable command bytes, and optionally publishes independently compilable kernel requests. Construction never roundtrips a module through text. Exact root ordinals let a high-throughput embedding resolve human-readable names once at ingress and use indexed identity throughout planning.

Without a request sink, construction leaves kernel implementation facets unopened. With a sink, it classifies only surviving source-backed launch sites and publishes one ordinary bytecode request per live semantic class. Published requests transfer independently and are never retained by the product.

Setting artifact_flags to LOOMC_EMIT_ARTIFACT_FLAG_TARGET_LISTING also returns one text artifact in the result, with format LOOMC_ARTIFACT_FORMAT_CMD_PROGRAM_LISTING and identifier command-program.listing. It contains the lowered command roots in product order, including repeated roots. Listing bytes belong to the result, not the product; neither retains the temporary compiler plan. Zero flags skip formatting entirely. The primary executable product is always returned, with or without LOOMC_EMIT_ARTIFACT_FLAG_PRIMARY.

Example

Build one command product from an already resolved root:

loomc_cmd_program_product_options_t options = {
    .type = LOOMC_STRUCTURE_TYPE_CMD_PROGRAM_PRODUCT_OPTIONS,
    .structure_size = sizeof(options),
    .compiler = compiler,
    .root_symbol_ordinals = &root_symbol_ordinal,
    .root_symbol_count = 1,
};
loomc_product_t* product = NULL;
loomc_result_t* result = NULL;
loomc_status_t status = loomc_cmd_program_product_build(
    workspace, &options, loomc_allocator_system(), &product, &result);
if (loomc_status_is_ok(status) && loomc_result_succeeded(result)) {
  loomc_cmd_program_t program;
  if (loomc_cmd_program_product_program_at(product, 0, &program)) {
    // Load or cache program.artifact.contents.
  }
}
loomc_result_release(result);
loomc_product_release(product);

Enumeration Type Documentation

loomc_cmd_program_product_flag_bits_t

enum loomc_cmd_program_product_flag_bits_t

Command-product operation flag bits.

Enumerator
LOOMC_CMD_PROGRAM_PRODUCT_FLAG_INCLUDE_INPUT_EXPORTS	Select exported command definitions from INPUT providers in addition to explicitly supplied roots.

Function Documentation

loomc_cmd_program_product_build()

loomc_status_t loomc_cmd_program_product_build	(	loomc_workspace_t *	workspace,
		const loomc_cmd_program_product_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_product_t **	out_product,
		loomc_result_t **	out_result )

Builds portable command programs and optional kernel source requests.

The returned product has the command descriptor, one executable artifact and exported root per selected command root, and one requirement per product-wide executable-entry binding. Command-specific queries expose the root symbols, root-to-requirement projections, and requirement symbols. The product owns all serialized bytes and copied names and retains no source module, link index, workspace, compiler plan, or analysis state.

Parameters

workspace	Invocation-local compiler workspace.
options	Product selection and specialization options.
allocator	Host allocator used for returned product and result state.
out_product	Receives one retained product when the result succeeds; receives NULL when the result fails.
out_result	Receives one retained result for the operation.

Returns

OK when the operation ran to a result. Non-OK statuses represent structural API misuse, callback failure, or infrastructure failure.

Ownership

The caller owns out_product when non-NULL and releases it with loomc_product_release. The caller owns out_result on an OK return and releases it with loomc_result_release. Each request is transferred independently to options->request_sink.

Lifetime

The operation borrows options, its arrays, link_index, and workspace synchronously. The returned product and published requests borrow none of them.

Thread safety

Calls may share a frozen link index. Each concurrent call requires a distinct workspace. Callback synchronization is owned by the embedding.

loomc_cmd_program_product_build_module()

loomc_status_t loomc_cmd_program_product_build_module	(	loomc_workspace_t *	workspace,
		const loomc_module_t *	module,
		const loomc_cmd_program_module_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_product_t **	out_product,
		loomc_result_t **	out_result )

Builds portable command programs from a materialized module.

The operation creates an invocation-local index over module, resolves named roots in that exact provider, and directly plans the command product. It does not serialize or reparse the input module. An optional frozen library index supplies dependencies without being traversed or copied.

Parameters

workspace	Invocation-local compiler workspace.
module	Immutable materialized INPUT module.
options	Product selection and specialization options.
allocator	Host allocator used for returned product and result state.
out_product	Receives one retained product when the result succeeds; receives NULL when the result fails.
out_result	Receives one retained result for the operation.

Returns

OK when the operation ran to a result. Non-OK statuses represent structural API misuse, callback failure, or infrastructure failure.

Ownership

The caller owns out_product when non-NULL and releases it with loomc_product_release. The caller owns out_result on an OK return and releases it with loomc_result_release. Each request is transferred independently to options->request_sink.

Lifetime

The operation borrows workspace, module, options, and the optional library index synchronously. The product and published requests retain none of them.

Thread safety

Calls may share an immutable module and frozen library index. Each concurrent call requires a distinct workspace. Callback synchronization is owned by the embedding.

loomc_cmd_program_product_build_request()

loomc_status_t loomc_cmd_program_product_build_request	(	loomc_context_t *	context,
		loomc_workspace_t *	workspace,
		const loomc_request_t *	request,
		const loomc_cmd_program_request_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_product_t **	out_product,
		loomc_result_t **	out_result )

Builds portable command programs from an ordinary bytecode request.

The operation indexes only request, maps its exact roots into an overlay over options->library_index, and directly plans the command product. It does not reparse names or serialize an intermediate linked request. The returned product preserves request-root order as export order. Published kernel requests carry provisional bindings to its executable-entry requirements.

Parameters

context	Context used to decode the request and shared with the optional library index.
workspace	Invocation-local compiler workspace.
request	Immutable request requiring a command-program product.
options	Product selection and specialization options, or NULL.
allocator	Host allocator used for returned product and result state.
out_product	Receives one retained product when the result succeeds; receives NULL when the result fails.
out_result	Receives one retained result for the operation.

Returns

OK when the operation ran to a result. Non-OK statuses represent structural API misuse, callback failure, or infrastructure failure.

Ownership

The caller owns out_product when non-NULL and releases it with loomc_product_release. The caller owns out_result on an OK return and releases it with loomc_result_release. Each request is transferred independently to options->request_sink.

Lifetime

The operation borrows context, workspace, request, options, and the optional library index synchronously. The product and published requests retain none of them.

Thread safety

Calls may share a context, immutable request, and frozen library index. Each concurrent call requires a distinct workspace. Callback synchronization is owned by the embedding.

loomc_cmd_program_product_descriptor()

const loomc_product_descriptor_t * loomc_cmd_program_product_descriptor

(

void

)

Returns the process-local command-product descriptor.

The returned pointer may be compared with loomc_product_descriptor to identify products before using command-specific projections.

Returns

Process-lifetime command-product descriptor.

loomc_cmd_program_product_entry_requirement_at()

bool loomc_cmd_program_product_entry_requirement_at	(	const loomc_product_t *	product,
		loomc_host_size_t	ordinal,
		loomc_cmd_entry_requirement_t *	out_requirement )

Returns an executable-entry requirement by product-local ordinal.

Parameters

product	Product to query.
ordinal	Product-local entry-requirement ordinal.
out_requirement	Receives the borrowed requirement when found.

Returns

True when ordinal was valid and out_requirement was populated.

loomc_cmd_program_product_entry_requirement_count()

loomc_host_size_t loomc_cmd_program_product_entry_requirement_count

(

const loomc_product_t *

product

)

Returns the number of product-wide executable-entry requirements.

Parameters

product

Product to query.

Returns

Number of product-wide executable-entry requirements.

loomc_cmd_program_product_program_at()

bool loomc_cmd_program_product_program_at	(	const loomc_product_t *	product,
		loomc_host_size_t	ordinal,
		loomc_cmd_program_t *	out_program )

Returns serialized command-root metadata by product-local ordinal.

Parameters

product	Product to query.
ordinal	Product-local root ordinal.
out_program	Receives the borrowed root record when found.

Returns

True when ordinal was valid and out_program was populated.

loomc_cmd_program_product_program_count()

loomc_host_size_t loomc_cmd_program_product_program_count

(

const loomc_product_t *

product

)

Returns the number of serialized command roots in product.

Parameters

product

Product to query.

Returns

Number of serialized command roots.