Status codes and rich infrastructure error reporting. More...

Data Structures
struct	loomc_status_source_location_t
	Source location captured when rich status mode supports it. More...

Macros
#define	LOOMC_STATUS_FEATURE_SOURCE_LOCATION (1 << 0)
	Status mode feature bit for source file and line capture.
#define	LOOMC_STATUS_FEATURE_ANNOTATIONS (1 << 1)
	Status mode feature bit for annotated messages.
#define	LOOMC_STATUS_FEATURE_STACK_TRACE (1 << 2)
	Status mode feature bit for stack trace capture.
#define	LOOMC_STATUS_MODE 3
	Rich status storage mode.
#define	LOOMC_STATUS_FEATURES 0
	Feature bit mask derived from LOOMC_STATUS_MODE.
#define	loomc_make_status(code, message)
	Allocates a status with the current source file and line.
#define	LOOMC_RETURN_IF_ERROR(expr)
	Returns immediately when an expression produces a non-OK status.

Enumerations
enum	loomc_status_code_t { LOOMC_STATUS_OK = 0 , LOOMC_STATUS_CANCELLED = 1 , LOOMC_STATUS_UNKNOWN = 2 , LOOMC_STATUS_INVALID_ARGUMENT = 3 , LOOMC_STATUS_DEADLINE_EXCEEDED = 4 , LOOMC_STATUS_NOT_FOUND = 5 , LOOMC_STATUS_ALREADY_EXISTS = 6 , LOOMC_STATUS_PERMISSION_DENIED = 7 , LOOMC_STATUS_RESOURCE_EXHAUSTED = 8 , LOOMC_STATUS_FAILED_PRECONDITION = 9 , LOOMC_STATUS_ABORTED = 10 , LOOMC_STATUS_OUT_OF_RANGE = 11 , LOOMC_STATUS_UNIMPLEMENTED = 12 , LOOMC_STATUS_INTERNAL = 13 , LOOMC_STATUS_UNAVAILABLE = 14 , LOOMC_STATUS_DATA_LOSS = 15 , LOOMC_STATUS_UNAUTHENTICATED = 16 , LOOMC_STATUS_DEFERRED = 17 , LOOMC_STATUS_INCOMPATIBLE = 18 , LOOMC_STATUS_CODE_MASK = 0x1Fu }
	Stable status codes shared by all Loom status modes. More...

Functions
loomc_status_t	loomc_status_allocate (loomc_status_code_t code, const char *file, uint32_t line, loomc_string_view_t message)
	Allocates a rich status when enabled by LOOMC_STATUS_MODE.
void	loomc_status_free (loomc_status_t status)
	Frees status storage, if any.
loomc_status_code_t	loomc_status_consume_code (loomc_status_t status)
	Frees status storage and returns its code.
loomc_status_t	loomc_status_join (loomc_status_t base_status, loomc_status_t new_status)
	Joins two statuses without discarding cleanup failures.
const char *	loomc_status_code_string (loomc_status_code_t code)
	Returns a stable C string naming code.
loomc_string_view_t	loomc_status_message (loomc_status_t status)
	Returns the primary message stored in status.
loomc_status_source_location_t	loomc_status_source_location (loomc_status_t status)
	Returns the source location captured by status, when available.
bool	loomc_status_format (loomc_status_t status, loomc_host_size_t buffer_capacity, char buffer, loomc_host_size_t out_length)
	Formats status into buffer using the two-pass pattern.

Detailed Description

Status codes and rich infrastructure error reporting.

loomc_status_t reports API misuse, allocation failure, cancellation infrastructure, and other failures that prevent an operation result from being produced. Source, linker, compiler, and configuration failures that are part of a completed operation are reported through result state and diagnostics instead of being hidden in status.

Status values are ABI-compatible with IREE status values when loomc/iree.h is included, but core Loom C API headers do not expose IREE types.

Example: Consume or free every non-OK status exactly once:

// `do_work` stands in for a status-returning API or application helper.
loomc_status_t status = do_work();
if (!loomc_status_is_ok(status)) {
  loomc_string_view_t message = loomc_status_message(status);
  if (!loomc_string_view_is_empty(message)) {
    fwrite(message.data, 1, message.size, stderr);
  }
  return (int)loomc_status_consume_code(status);
}

Macro Definition Documentation

◆ loomc_make_status

#define loomc_make_status	(		code,
			message )

Value:

loomc_status_allocate((code), __FILE__, __LINE__, \

loomc_make_cstring_view(message))

loomc_status_allocate

loomc_status_t loomc_status_allocate(loomc_status_code_t code, const char *file, uint32_t line, loomc_string_view_t message)

Allocates a rich status when enabled by LOOMC_STATUS_MODE.

Allocates a status with the current source file and line.

Parameters

code	Status code to report.
message	NUL-terminated human-readable message.

Returns: A status carrying code and message.

◆ LOOMC_RETURN_IF_ERROR

#define LOOMC_RETURN_IF_ERROR ( expr )

Value:

do {                                   \
  loomc_status_t status__ = (expr);    \
  if (!loomc_status_is_ok(status__)) { \
    return status__;                   \
  }                                    \
} while (0)

Returns immediately when an expression produces a non-OK status.

Parameters

expr	Status-returning expression to evaluate exactly once.

◆ LOOMC_STATUS_MODE

#define LOOMC_STATUS_MODE 3

Rich status storage mode.

Mode 0 stores status codes only and performs no rich status allocation. Mode 1 adds source locations. Mode 2 adds annotations. Mode 3 adds stack traces. Release builds default to mode 2; non-release builds default to mode 3.

Enumeration Type Documentation

◆ loomc_status_code_t

enum loomc_status_code_t

Stable status codes shared by all Loom status modes.

The numeric values are stable ABI and intentionally match the values used by optional IREE adapters so statuses can be passed across that boundary without conversion or information loss.

Enumerator
LOOMC_STATUS_OK	Successful operation.
LOOMC_STATUS_CANCELLED	Operation was cancelled by the caller.
LOOMC_STATUS_UNKNOWN	Unknown error or unmapped failure.
LOOMC_STATUS_INVALID_ARGUMENT	The caller provided an invalid argument.
LOOMC_STATUS_DEADLINE_EXCEEDED	A deadline was exceeded before the call completed.
LOOMC_STATUS_NOT_FOUND	A referenced resource could not be found.
LOOMC_STATUS_ALREADY_EXISTS	The resource the caller attempted to create already exists.
LOOMC_STATUS_PERMISSION_DENIED	The caller does not have permission for the requested operation.
LOOMC_STATUS_RESOURCE_EXHAUSTED	A required resource was exhausted.
LOOMC_STATUS_FAILED_PRECONDITION	The system is not in a required state for the operation.
LOOMC_STATUS_ABORTED	The operation was aborted by the system.
LOOMC_STATUS_OUT_OF_RANGE	The operation was attempted outside a valid range.
LOOMC_STATUS_UNIMPLEMENTED	The operation has not been implemented or is not supported.
LOOMC_STATUS_INTERNAL	An internal invariant was violated.
LOOMC_STATUS_UNAVAILABLE	The underlying system is currently unavailable.
LOOMC_STATUS_DATA_LOSS	Unrecoverable data loss or corruption occurred.
LOOMC_STATUS_UNAUTHENTICATED	The requested operation does not have proper authentication.
LOOMC_STATUS_DEFERRED	The operation has been deferred and must be resumed later.
LOOMC_STATUS_INCOMPATIBLE	The program or environment is incompatible with the request.
LOOMC_STATUS_CODE_MASK	Mask covering all status code bits in a loomc_status_t value.

Function Documentation

◆ loomc_status_allocate()

loomc_status_t loomc_status_allocate	(	loomc_status_code_t	code,
		const char *	file,
		uint32_t	line,
		loomc_string_view_t	message )

Allocates a rich status when enabled by LOOMC_STATUS_MODE.

Parameters

code	Status code to report.
file	Source file path associated with the failure.
line	Source line associated with the failure.
message	Primary human-readable message. The message bytes are copied when rich status storage is enabled.

Returns: A status carrying code and any rich payload enabled by the current status mode.

Ownership: Non-OK returned statuses must eventually be passed to loomc_status_free, loomc_status_consume_code, or loomc_status_join.

◆ loomc_status_code_string()

const char * loomc_status_code_string ( loomc_status_code_t code )

Returns a stable C string naming code.

Parameters

code	Status code to name.

Returns: Static NUL-terminated string owned by the library.

◆ loomc_status_consume_code()

loomc_status_code_t loomc_status_consume_code ( loomc_status_t status )

Frees status storage and returns its code.

Parameters

status Status to consume.

Returns: Code carried by status.

◆ loomc_status_format()

bool loomc_status_format	(	loomc_status_t	status,
		loomc_host_size_t	buffer_capacity,
		char *	buffer,
		loomc_host_size_t *	out_length )

Formats status into buffer using the two-pass pattern.

Parameters

status	Status to format.
buffer_capacity	Number of bytes available in buffer.
buffer	Output buffer, or NULL when querying the required length.
out_length	Receives the number of bytes required or written, excluding any trailing NUL byte.

Returns: True when buffer was large enough and formatting completed.

Lifetime: Formatted bytes are owned by the caller-provided buffer.

◆ loomc_status_free()

void loomc_status_free ( loomc_status_t status )

Frees status storage, if any.

Parameters

status Status to free. Passing OK or a code-only status is allowed.

◆ loomc_status_join()

loomc_status_t loomc_status_join	(	loomc_status_t	base_status,
		loomc_status_t	new_status )

Joins two statuses without discarding cleanup failures.

Parameters

base_status	Existing status, often the primary operation status.
new_status	New status, often produced by cleanup.

Returns: A status that preserves a non-OK status when either input failed.

Ownership: The returned status owns any retained rich payload. The caller must not use base_status or new_status after passing them to this function.

◆ loomc_status_message()

loomc_string_view_t loomc_status_message ( loomc_status_t status )

Returns the primary message stored in status.

Parameters

status Status to inspect.

Returns: Borrowed message view owned by status, or an empty view when no message is available.

Lifetime: The returned view remains valid until status is freed or consumed.

◆ loomc_status_source_location()

loomc_status_source_location_t loomc_status_source_location ( loomc_status_t status )

Returns the source location captured by status, when available.

Parameters

status Status to inspect.

Returns: Source location payload, or empty fields when unavailable.

Lifetime: The returned file view remains valid until status is freed or consumed.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ loomc_make_status

◆ LOOMC_RETURN_IF_ERROR

◆ LOOMC_STATUS_MODE

Enumeration Type Documentation

◆ loomc_status_code_t

Function Documentation

◆ loomc_status_allocate()

◆ loomc_status_code_string()

◆ loomc_status_consume_code()

◆ loomc_status_format()

◆ loomc_status_free()

◆ loomc_status_join()

◆ loomc_status_message()

◆ loomc_status_source_location()