product.h File Reference

Immutable compiler products and their recursively published requests. More...

Go to the source code of this file.

Data Structures
struct	loomc_request_root_t
	Durable address of one root in a request's bytecode source. More...
struct	loomc_request_binding_t
	Provisional association between a parent requirement and a request root. More...
struct	loomc_request_sink_t
	Optional destination for streamed product requests. More...

Macros
#define	LOOMC_REQUIREMENT_ORDINAL_INVALID   UINT32_MAX
	Invalid parent-product requirement ordinal.
#define	LOOMC_REQUEST_ROOT_ORDINAL_INVALID   UINT32_MAX
	Invalid request-local root ordinal.

Typedefs
typedef struct loomc_product_descriptor_t	loomc_product_descriptor_t
	Opaque process-local identity for one product representation.
typedef struct loomc_product_t	loomc_product_t
	Immutable successful compiler product.
typedef uint32_t	loomc_requirement_ordinal_t
	Parent-product-local requirement ordinal.
typedef uint32_t	loomc_request_root_ordinal_t
	Request-local root ordinal.
typedef struct loomc_request_t	loomc_request_t
	Immutable independently compilable product request.
typedef loomc_status_t(*	loomc_request_publish_fn_t) (void *user_data, loomc_request_t *request)
	Accepts ownership of one published request at callback entry.

Functions
void	loomc_product_retain (loomc_product_t *product)
	Retains a product for another owner.
void	loomc_product_release (loomc_product_t *product)
	Releases a product.
const loomc_product_descriptor_t *	loomc_product_descriptor (const loomc_product_t *product)
	Returns the process-local descriptor identifying product.
loomc_host_size_t	loomc_product_artifact_count (const loomc_product_t *product)
	Returns the number of artifacts owned by product.
const loomc_artifact_t *	loomc_product_artifact_at (const loomc_product_t *product, loomc_host_size_t ordinal)
	Returns an artifact by product-local ordinal.
loomc_host_size_t	loomc_product_export_count (const loomc_product_t *product)
	Returns the number of roots exported by product.
loomc_host_size_t	loomc_product_requirement_count (const loomc_product_t *product)
	Returns the number of unresolved requirements in product.
loomc_status_t	loomc_request_create (const loomc_product_descriptor_t *product_descriptor, loomc_source_t *source, const loomc_request_root_t *roots, loomc_host_size_t root_count, const loomc_request_binding_t *bindings, loomc_host_size_t binding_count, loomc_allocator_t allocator, loomc_request_t **out_request)
	Creates an immutable request over ordinary Loom bytecode.
void	loomc_request_retain (loomc_request_t *request)
	Retains a request for another owner.
void	loomc_request_release (loomc_request_t *request)
	Releases a request.
const loomc_product_descriptor_t *	loomc_request_product_descriptor (const loomc_request_t *request)
	Returns the required product representation for request.
loomc_source_t *	loomc_request_source (const loomc_request_t *request)
	Returns the immutable bytecode source owned by request.
loomc_host_size_t	loomc_request_root_count (const loomc_request_t *request)
	Returns the number of canonical roots in request.
bool	loomc_request_root_at (const loomc_request_t *request, loomc_request_root_ordinal_t ordinal, loomc_request_root_t *out_root)
	Returns a request root by request-local ordinal.
loomc_host_size_t	loomc_request_binding_count (const loomc_request_t *request)
	Returns the number of provisional parent bindings in request.
bool	loomc_request_binding_at (const loomc_request_t *request, loomc_host_size_t ordinal, loomc_request_binding_t *out_binding)
	Returns a provisional parent binding by ordinal.

Detailed Description

Immutable compiler products and their recursively published requests.

A product is the immutable value returned by a successful compiler operation. It owns that operation's artifacts and exposes the two ordinal spaces needed for composition: exported roots that may satisfy a parent binding and requirements that must be satisfied by child products or an embedding. Product-specific APIs project richer metadata from the same handle without changing its ownership model.

loomc_result_t and loomc_product_t deliberately answer different questions. A result reports whether an operation succeeded and carries its diagnostics. A product exists only on success and carries the immutable value produced by the operation.

A request is an independently compilable ordinary Loom bytecode source. It owns the exact source roots selected by its producer and the provisional bindings from requirements in the parent product to those roots. Requests retain no mutable module, workspace, link plan, or compiler analysis state.

Every request names the process-local product descriptor it expects a successful pipeline to produce. This is the open compilation route used by hosts: command programs, compiled modules, and future product families add descriptors without extending a central kind enumeration. Root operations remain the durable source contract and are validated by the selected product operation. Symbol strings, filenames, and target names do not participate in routing.

Typedef Documentation

loomc_product_descriptor_t

typedef struct loomc_product_descriptor_t loomc_product_descriptor_t

Opaque process-local identity for one product representation.

Descriptor pointers are stable for the lifetime of the process and may be compared by identity. They are never serialized. A request uses the descriptor to name its required successful representation while its source roots retain the durable operation contracts compiled by that route.

loomc_product_t

typedef struct loomc_product_t loomc_product_t

Immutable successful compiler product.

Product artifacts, exported roots, and requirements use product-local ordinals. An operation-specific API defines the metadata and meaning of each root and requirement. A request binding associates one requirement ordinal in a parent product with one root ordinal in a child request; the resulting child product preserves that request-root order as its exported root order.

Thread safety

Products are immutable after construction. Retained handles may be queued, cached, and shared across threads independently of the producing compiler invocation.

loomc_request_publish_fn_t

typedef loomc_status_t(* loomc_request_publish_fn_t) (void *user_data, loomc_request_t *request)

Accepts ownership of one published request at callback entry.

Parameters

user_data	Callback-owned state.
request	Request reference transferred to the callback.

Returns

OK to continue publication or a non-OK status to terminate the parent operation.

Ownership

The callback owns request at entry, including when it returns a non-OK status. It must release or transfer that reference.

Transaction

Publication is provisional until the parent operation returns OK with a succeeded result. Accepted requests remain receiver-owned and independently usable when the parent operation is cancelled, but their parent bindings must not be committed.

loomc_request_t

typedef struct loomc_request_t loomc_request_t

Immutable independently compilable product request.

Thread safety

Requests are immutable after publication. Retained handles may be queued, cached, and shared across threads independently of the producer lifetime.

Function Documentation

loomc_product_artifact_at()

const loomc_artifact_t * loomc_product_artifact_at	(	const loomc_product_t *	product,
		loomc_host_size_t	ordinal )

Returns an artifact by product-local ordinal.

Parameters

product	Product to inspect.
ordinal	Zero-based artifact ordinal.

Returns

Borrowed artifact view, or NULL when ordinal is out of range.

Lifetime

The returned view and its strings remain valid while product is retained. Callers that need independent byte ownership retain artifact->contents.

loomc_product_artifact_count()

loomc_host_size_t loomc_product_artifact_count

(

const loomc_product_t *

product

)

Returns the number of artifacts owned by product.

Parameters

product

Product to inspect, or NULL.

Returns

Artifact count, or zero for a NULL product.

loomc_product_descriptor()

const loomc_product_descriptor_t * loomc_product_descriptor

(

const loomc_product_t *

product

)

Returns the process-local descriptor identifying product.

Parameters

product

Product to inspect, or NULL.

Returns

Product descriptor, or NULL for a NULL product.

loomc_product_export_count()

loomc_host_size_t loomc_product_export_count

(

const loomc_product_t *

product

)

Returns the number of roots exported by product.

Export ordinals preserve the root order of the request or direct build that produced the product. Product-specific APIs expose root metadata.

Parameters

product

Product to inspect, or NULL.

Returns

Exported-root count, or zero for a NULL product.

loomc_product_release()

void loomc_product_release

(

loomc_product_t *

product

)

Releases a product.

Parameters

product

Product to release. Passing NULL is allowed.

loomc_product_requirement_count()

loomc_host_size_t loomc_product_requirement_count

(

const loomc_product_t *

product

)

Returns the number of unresolved requirements in product.

Requirements are addressed by loomc_requirement_ordinal_t. Their typed contracts are exposed by product-specific APIs; source requests carry the provisional child bindings needed by a composing host.

Parameters

product

Product to inspect, or NULL.

Returns

Requirement count, or zero for a NULL product.

loomc_product_retain()

void loomc_product_retain

(

loomc_product_t *

product

)

Retains a product for another owner.

Parameters

product

Product to retain. Passing NULL is allowed.

loomc_request_binding_at()

bool loomc_request_binding_at	(	const loomc_request_t *	request,
		loomc_host_size_t	ordinal,
		loomc_request_binding_t *	out_binding )

Returns a provisional parent binding by ordinal.

Parameters

request	Request to inspect.
ordinal	Zero-based binding ordinal.
out_binding	Receives the binding when found.

Returns

True when ordinal was valid and out_binding was populated.

loomc_request_binding_count()

loomc_host_size_t loomc_request_binding_count

(

const loomc_request_t *

request

)

Returns the number of provisional parent bindings in request.

Parameters

request

Request to inspect, or NULL.

Returns

Binding count, or zero for a NULL request.

loomc_request_create()

loomc_status_t loomc_request_create	(	const loomc_product_descriptor_t *	product_descriptor,
		loomc_source_t *	source,
		const loomc_request_root_t *	roots,
		loomc_host_size_t	root_count,
		const loomc_request_binding_t *	bindings,
		loomc_host_size_t	binding_count,
		loomc_allocator_t	allocator,
		loomc_request_t **	out_request )

Creates an immutable request over ordinary Loom bytecode.

Parameters

product_descriptor	Process-lifetime descriptor for the required successful product representation.
source	Bytecode source retained by the request.
roots	Source-local roots copied in product export order.
root_count	Number of entries in roots; must be nonzero.
bindings	Optional parent-requirement bindings copied into the request. Entries must have strictly increasing requirement ordinals and refer to valid request-local roots.
binding_count	Number of entries in bindings.
allocator	Host allocator used for request and metadata storage.
out_request	Receives one retained request.

Returns

OK when the immutable request was created.

Root addresses are validated against the bytecode source by the operation that consumes the request. This constructor performs no source indexing or module scan, so a caller may resolve human-readable names once through a link index and form many requests by exact ordinal.

Ownership

The caller retains source and owns the returned request. Release the request with loomc_request_release.

Thread safety

Creation is local to the caller. The returned request is immutable and may be retained and shared across threads.

loomc_request_product_descriptor()

const loomc_product_descriptor_t * loomc_request_product_descriptor

(

const loomc_request_t *

request

)

Returns the required product representation for request.

The descriptor is part of the immutable request contract. A pipeline selected for the request must produce a product with this descriptor on success. Descriptor identity is process-local and is never serialized into the request source.

Parameters

request

Request to inspect, or NULL.

Returns

Required product descriptor, or NULL for a NULL request.

loomc_request_release()

void loomc_request_release

(

loomc_request_t *

request

)

Releases a request.

Parameters

request

Request to release. Passing NULL is allowed.

loomc_request_retain()

void loomc_request_retain

(

loomc_request_t *

request

)

Retains a request for another owner.

Parameters

request

Request to retain. Passing NULL is allowed.

loomc_request_root_at()

bool loomc_request_root_at	(	const loomc_request_t *	request,
		loomc_request_root_ordinal_t	ordinal,
		loomc_request_root_t *	out_root )

Returns a request root by request-local ordinal.

Parameters

request	Request to inspect.
ordinal	Request-local root ordinal.
out_root	Receives the root when found.

Returns

True when ordinal was valid and out_root was populated.

loomc_request_root_count()

loomc_host_size_t loomc_request_root_count

(

const loomc_request_t *

request

)

Returns the number of canonical roots in request.

Parameters

request

Request to inspect, or NULL.

Returns

Root count, or zero for a NULL request.

loomc_request_source()

loomc_source_t * loomc_request_source

(

const loomc_request_t *

request

)

Returns the immutable bytecode source owned by request.

Parameters

request

Request to inspect.

Returns

Borrowed bytecode source, or NULL for a NULL request.

Lifetime

The source remains valid while request is retained. Callers that need an independent source reference retain it with loomc_source_retain.