execution_observer.h File Reference

#include <stdint.h>
#include <pineforge/pineforge.h>

Include dependency graph for execution_observer.h:

Go to the source code of this file.

Data Structures
struct	pf_execution_boundary_v1
	Boundary handed to the observer. More...
struct	pf_boundary_receipt_v1
	Receipt the callback fills. More...
struct	pf_execution_observer_v1
	Observer descriptor for strategy_set_execution_observer_v1(). More...
struct	pf_execution_observation_v1
	Snapshot of the execution state, filled by strategy_execution_observation_v1(). More...

Typedefs
typedef int(*	pf_before_results_fn_v1) (void *context, const pf_execution_boundary_v1 *boundary, pf_boundary_receipt_v1 *receipt)
	Observer callback.

Functions
uint32_t	pf_execution_observer_version (void)
	Returns the execution observer ABI version, 1.
int	strategy_set_execution_observer_v1 (pf_strategy_t, const pf_execution_observer_v1 *)
	Registers, replaces or removes the strategy's execution observer.
int	strategy_execution_observation_v1 (pf_strategy_t, pf_execution_observation_v1 *)
	Copies one complete observation into *out.

Typedef Documentation

pf_before_results_fn_v1

typedef int(* pf_before_results_fn_v1) (void *context, const pf_execution_boundary_v1 *boundary, pf_boundary_receipt_v1 *receipt)

Observer callback.

The runtime calls it once, synchronously, after the generation seals on a successful terminal path and before results open. A failed or aborted generation closes without a successful callback. An exception thrown here is a failure and never unwinds through C. boundary and receipt are valid for this call only; context follows the registration lifetime.

Definition at line 73 of file execution_observer.h.

Function Documentation

pf_execution_observer_version()

uint32_t pf_execution_observer_version

(

void

)

Returns the execution observer ABI version, 1.

References PF_API.

strategy_set_execution_observer_v1()

int strategy_set_execution_observer_v1	(	pf_strategy_t	,
		const pf_execution_observer_v1 *	)

Registers, replaces or removes the strategy's execution observer.

Returns 0 when accepted; -1 for an invalid struct_size or version, a null before_results or a null strategy handle; -2 for an unsupported execution contract (not a purity assertion or an unknown-override detector); -3 for a nonquiescent or reentrant call; -4 when the private consumer storage cannot be allocated. No exception crosses C.

Registration copies the descriptor's values. context and before_results stay borrowed until a successful replacement or removal, or until the strategy is destroyed. A NULL descriptor removes the registration, but only when quiescent. A refusal leaves the installed descriptor unchanged. A forbidden reentry keeps its first cause latched, as the existing entry contract requires; an ordinary busy refusal does not rewrite a run outcome. Destroying the strategy never calls the observer.

References PF_API.

strategy_execution_observation_v1()

int strategy_execution_observation_v1	(	pf_strategy_t	,
		pf_execution_observation_v1 *	)

Copies one complete observation into *out.

The caller first sets out->struct_size and out->version.

Returns 0 with one complete snapshot, or -1 with *out unchanged. Allowed inside the observer; it dispatches no host code and allocates no missing consumer. A fresh or copied consumer reports generation 0 and no owned result. This is observation only, not permission to publish stale output.

References PF_API.