result.h File Reference

Shared operation result container. More...

Go to the source code of this file.

Typedefs
typedef struct loomc_result_t	loomc_result_t
	Immutable operation result.

Enumerations
enum	loomc_result_state_t { LOOMC_RESULT_STATE_SUCCEEDED = 0 , LOOMC_RESULT_STATE_FAILED = 1 , LOOMC_RESULT_STATE_CANCELLED = 2 }
	Terminal operation-domain state. More...

Functions
void	loomc_result_retain (loomc_result_t *result)
	Retains result for another owner.
void	loomc_result_release (loomc_result_t *result)
	Releases result from one owner.
loomc_result_state_t	loomc_result_state (const loomc_result_t *result)
	Returns the result state.
bool	loomc_result_succeeded (const loomc_result_t *result)
	Returns true when result succeeded.
loomc_host_size_t	loomc_result_diagnostic_count (const loomc_result_t *result)
	Returns the number of diagnostics attached to result.
const loomc_diagnostic_t *	loomc_result_diagnostic_at (const loomc_result_t *result, loomc_host_size_t index)
	Returns a diagnostic by index.
loomc_host_size_t	loomc_result_artifact_count (const loomc_result_t *result)
	Returns the number of artifacts attached to result.
const loomc_artifact_t *	loomc_result_artifact_at (const loomc_result_t *result, loomc_host_size_t index)
	Returns an artifact by index.

Detailed Description

Shared operation result container.

A result exists when an operation completed far enough to report domain-specific state. API and infrastructure failures that prevent result creation are returned as non-OK loomc_status_t values instead.

Example

Check status first, then inspect the result. Diagnostics are structured data, not text that callers have to scrape:

loomc_result_t* result = NULL;
// `run_loom_operation` stands in for an operation-specific API that returns
// OK and writes a retained result when domain diagnostics are available.
loomc_status_t status = run_loom_operation(&result);
if (!loomc_status_is_ok(status)) {
  return status;
}
 
for (loomc_host_size_t i = 0; i < loomc_result_diagnostic_count(result);
     ++i) {
  const loomc_diagnostic_t* diagnostic =
      loomc_result_diagnostic_at(result, i);
  // `handle_diagnostic` is application-owned reporting policy.
  handle_diagnostic(diagnostic->severity, diagnostic->code,
                    diagnostic->message, diagnostic->range);
}
 
if (loomc_result_succeeded(result)) {
  for (loomc_host_size_t i = 0; i < loomc_result_artifact_count(result);
       ++i) {
    const loomc_artifact_t* artifact = loomc_result_artifact_at(result, i);
    // `handle_artifact` is application-owned loading or packaging policy.
    handle_artifact(artifact->kind, artifact->format,
                    artifact->contents);
  }
}
 
loomc_result_release(result);

Typedef Documentation

loomc_result_t

typedef struct loomc_result_t loomc_result_t

Immutable operation result.

Thread safety

Results are immutable after creation. Retained result handles may be shared across threads.

Enumeration Type Documentation

loomc_result_state_t

enum loomc_result_state_t

Terminal operation-domain state.

Enumerator
LOOMC_RESULT_STATE_SUCCEEDED	Operation succeeded and requested outputs are available.
LOOMC_RESULT_STATE_FAILED	Operation completed with diagnostics and no infrastructure status failure.
LOOMC_RESULT_STATE_CANCELLED	Operation completed after observing cancellation.

Function Documentation

loomc_result_artifact_at()

const loomc_artifact_t * loomc_result_artifact_at	(	const loomc_result_t *	result,
		loomc_host_size_t	index )

Returns an artifact by index.

Parameters

result	Result to inspect.
index	Zero-based artifact index.

Returns

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

Lifetime

The returned pointer remains valid until result is released.

loomc_result_artifact_count()

loomc_host_size_t loomc_result_artifact_count

(

const loomc_result_t *

result

)

Returns the number of artifacts attached to result.

Parameters

result

Result to inspect.

Returns

Artifact count.

loomc_result_diagnostic_at()

const loomc_diagnostic_t * loomc_result_diagnostic_at	(	const loomc_result_t *	result,
		loomc_host_size_t	index )

Returns a diagnostic by index.

Parameters

result	Result to inspect.
index	Zero-based diagnostic index.

Returns

Borrowed diagnostic view, or NULL when index is out of range.

Lifetime

The returned pointer remains valid until result is released.

loomc_result_diagnostic_count()

loomc_host_size_t loomc_result_diagnostic_count

(

const loomc_result_t *

result

)

Returns the number of diagnostics attached to result.

Parameters

result

Result to inspect.

Returns

Diagnostic count.

loomc_result_release()

void loomc_result_release

(

loomc_result_t *

result

)

Releases result from one owner.

Parameters

result

Result to release. Passing NULL is allowed.

Thread safety

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

loomc_result_retain()

void loomc_result_retain

(

loomc_result_t *

result

)

Retains result for another owner.

Parameters

result

Result to retain.

Thread safety

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

loomc_result_state()

loomc_result_state_t loomc_result_state

(

const loomc_result_t *

result

)

Returns the result state.

Parameters

result

Result to inspect.

Returns

Terminal operation-domain state.

loomc_result_succeeded()

bool loomc_result_succeeded

(

const loomc_result_t *

result

)

Returns true when result succeeded.

Parameters

result

Result to inspect.

Returns

True when loomc_result_state(result) is LOOMC_RESULT_STATE_SUCCEEDED.