pass_trace.h File Reference

Streaming pass-boundary IR traces. More...

Go to the source code of this file.

Data Structures
struct	loomc_pass_trace_sink_t
	Borrowed destination for one sequential pass trace. More...
struct	loomc_pass_trace_event_t
	Stable metadata available when opening one per-event artifact. More...
struct	loomc_pass_trace_artifact_t
	Caller-owned destination for one per-event trace artifact. More...
struct	loomc_pass_trace_artifact_sink_t
	Optional per-event artifact destination callbacks. More...
struct	loomc_pass_trace_options_t
	Pass trace options for one pipeline or compile invocation. More...

Typedefs
typedef uint32_t	loomc_pass_trace_flags_t
	Bitmask of loomc_pass_trace_flag_bits_t.
typedef loomc_status_t(*	loomc_pass_trace_write_fn_t) (void *user_data, loomc_string_view_t fragment)
	Writes one ordered trace fragment.
typedef loomc_status_t(*	loomc_pass_trace_artifact_open_fn_t) (void *user_data, const loomc_pass_trace_event_t *event, loomc_pass_trace_artifact_t *out_artifact)
	Opens one destination for a selected trace event.
typedef loomc_status_t(*	loomc_pass_trace_artifact_close_fn_t) (void *user_data, loomc_pass_trace_artifact_t *artifact)
	Closes one destination successfully returned from open.

Enumerations
enum	loomc_pass_trace_format_t { LOOMC_PASS_TRACE_FORMAT_TEXT = 0 , LOOMC_PASS_TRACE_FORMAT_JSONL = 1 }
	Formatted pass trace representation. More...
enum	loomc_pass_trace_flag_bits_t { LOOMC_PASS_TRACE_FLAG_BEFORE_ALL = 1u << 0 , LOOMC_PASS_TRACE_FLAG_AFTER_ALL = 1u << 1 }
	Pass trace selection bits. More...
enum	loomc_pass_trace_point_t { LOOMC_PASS_TRACE_POINT_BEFORE = 0 , LOOMC_PASS_TRACE_POINT_AFTER = 1 }
	Pass trace boundary point. More...

Detailed Description

Streaming pass-boundary IR traces.

Pass traces are cold diagnostic output produced while a prepared pass program executes. Loom owns event selection, compiler-state projection, and stable text or JSONL formatting. Callers own only the destination policy by supplying a synchronous write callback.

Typedef Documentation

loomc_pass_trace_artifact_close_fn_t

typedef loomc_status_t(* loomc_pass_trace_artifact_close_fn_t) (void *user_data, loomc_pass_trace_artifact_t *artifact)

Closes one destination successfully returned from open.

Close is invoked exactly once after a successful open, including when a sequential or artifact write fails. The callback releases all resources associated with artifact and transfers any returned status to Loom.

loomc_pass_trace_artifact_open_fn_t

typedef loomc_status_t(* loomc_pass_trace_artifact_open_fn_t) (void *user_data, const loomc_pass_trace_event_t *event, loomc_pass_trace_artifact_t *out_artifact)

Opens one destination for a selected trace event.

event is borrowed only for the callback duration. On an OK return, out_artifact must contain a non-empty reference and write callback that remain live until the matching close callback. A non-OK return retains all destination ownership with the callback and is not followed by close.

loomc_pass_trace_write_fn_t

typedef loomc_status_t(* loomc_pass_trace_write_fn_t) (void *user_data, loomc_string_view_t fragment)

Writes one ordered trace fragment.

fragment is borrowed only for the callback duration and may contain any number of bytes, including one byte. Returning a non-OK status stops the compile operation and transfers ownership of that status to Loom.

Enumeration Type Documentation

loomc_pass_trace_flag_bits_t

enum loomc_pass_trace_flag_bits_t

Pass trace selection bits.

Enumerator
LOOMC_PASS_TRACE_FLAG_BEFORE_ALL	Trace the IR immediately before every pass invocation.
LOOMC_PASS_TRACE_FLAG_AFTER_ALL	Trace the IR immediately after every pass invocation.

loomc_pass_trace_format_t

enum loomc_pass_trace_format_t

Formatted pass trace representation.

Enumerator
LOOMC_PASS_TRACE_FORMAT_TEXT	Human-readable event metadata followed by textual Loom IR.
LOOMC_PASS_TRACE_FORMAT_JSONL	One JSON object per event with JSON-escaped textual Loom IR.

loomc_pass_trace_point_t

enum loomc_pass_trace_point_t

Pass trace boundary point.

Enumerator
LOOMC_PASS_TRACE_POINT_BEFORE	Snapshot immediately before the selected pass invocation.
LOOMC_PASS_TRACE_POINT_AFTER	Snapshot immediately after the selected pass invocation.