selected_window.h File Reference

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

Include dependency graph for selected_window.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	pf_selected_window_config_v1
	Selected-window configuration, handed to strategy_set_selected_window_v1(). More...
struct	pf_selected_window_counts_v1
	Native-owned counts for the latest attempt, filled by strategy_selected_window_counts_v1(). More...

Functions
uint32_t	pf_selected_window_version (void)
	Returns the selected-window ABI version, 1.
int	strategy_set_selected_window_v1 (pf_strategy_t, const pf_selected_window_config_v1 *)
	Sets the pending selected-window configuration, or clears it with a NULL descriptor.
int	strategy_selected_window_counts_v1 (pf_strategy_t, pf_selected_window_counts_v1 *)
	Copies one complete counts snapshot for the latest attempt into *out.

Function Documentation

pf_selected_window_version()

uint32_t pf_selected_window_version

(

void

)

Returns the selected-window ABI version, 1.

References PF_API.

strategy_set_selected_window_v1()

int strategy_set_selected_window_v1	(	pf_strategy_t	,
		const pf_selected_window_config_v1 *	)

Sets the pending selected-window configuration, or clears it with a NULL descriptor.

A NULL descriptor disables selection for the next admitted generation. The setter copies only start_ms and end_ms.

Returns 0 when accepted; -1 for an invalid handle, struct_size, version or bounds; -2 for an unsupported execution contract (not a purity declaration or an override detector, and not permission to reject a custom presentation host); -3 for a nonquiescent or reentrant call; -4 when required private storage cannot be allocated. Every refusal leaves the configuration unchanged, and no exception crosses C.

The setter is quiescent only outside execution, capture and observer dispatch, including outside the existing preparing_begin, in_callback and processing_input barriers. Setting or clearing changes pending configuration only: it never reopens the provenance or results of an existing generation, rewrites the latest attempt or changes an existing capture. Configuration is copied into admitted state after the last begin refusal or reset and before the first admitted host callback, and a refused begin consumes no new selected generation. Copies and moves that discard the private consumer also discard pending configuration and any owned result, but preserve closed provenance.

References PF_API.

strategy_selected_window_counts_v1()

int strategy_selected_window_counts_v1	(	pf_strategy_t	,
		pf_selected_window_counts_v1 *	)

Copies one complete counts snapshot for the latest attempt into *out.

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

Returns 0 with one complete snapshot only when the latest attempt owns a successful selected Results generation. Returns -1 for a null handle or output, or a wrong struct_size or version. Returns -2 when no such result belongs to the latest attempt (fresh, copied, OFF, live, refused, failed, aborted or observer-faulted). On failure, valid caller storage is unchanged.

The getter never executes host code, allocates a missing consumer or materializes a report. Counts do not open early inside the observer, and these counters never authorize charges.

References PF_API.