Recorded outputs

What a module records besides trades, read after a run or between the inputs of a stream (docs/outputs.md). More...

Data Structures
struct	pf_output_event_v1_t
	One recorded event, copied by strategy_outputs_event_get. More...

Macros
#define	PINEFORGE_HAS_OUTPUTS_V1   1
	Present in a pineforge.h that declares the group.
#define	PF_OUTPUTS_API_VERSION   1u
	What strategy_outputs_api_version answers.

Enumerations
enum	pf_output_phase_t {   PF_OUTPUT_PHASE_BATCH = 0 ,   PF_OUTPUT_PHASE_WARMUP = 1 ,   PF_OUTPUT_PHASE_REALTIME = 2 }
	The run phase an event was recorded in. More...

Functions
	PF_STATIC_ASSERT (sizeof(pf_output_phase_t)==4)
int	strategy_outputs_set_enabled (pf_strategy_t s, int on)
	Turn recording on (on nonzero) or off.
int	strategy_outputs_series_count (pf_strategy_t s)
	Series slots per row; 0 while recording is off.
int64_t	strategy_outputs_bars_len (pf_strategy_t s)
	Rows recorded: one per bar the module published this run.
int	strategy_outputs_bar_times_copy (pf_strategy_t s, int64_t from_bar, int64_t *open_ms, int64_t *close_ms, int64_t capacity, int64_t *written)
	Copy the open and close times (Unix ms) of rows from from_bar on.
int	strategy_outputs_series_copy (pf_strategy_t s, int series, int64_t from_bar, double *out, int64_t capacity, int64_t *written)
	Copy one slot's values (NaN = na) of rows from from_bar on, as strategy_outputs_bar_times_copy does; out is required when capacity > 0, and series must be below the series count.
int	strategy_outputs_events_len (pf_strategy_t s)
	Events queued since the run began or since the last clear.
int	strategy_outputs_event_get (pf_strategy_t s, int index, void *out, size_t size_in)
	Copy event index into out: min(size_in, sizeof(pf_output_event_v1_t)) bytes, so an older or newer caller's struct works.
void	strategy_outputs_events_clear (pf_strategy_t s)
	Drop the queued events, in every mode; rows and the sequence are kept.
int	strategy_outputs_constants_copy (pf_strategy_t s, double *out, int capacity)
	Copy the run constants (NaN = na, or not written this run) into out: the first min(capacity, n) of them.
uint32_t	strategy_outputs_api_version (void)
	Part A: PF_OUTPUTS_API_VERSION.
int	strategy_outputs_manifest (pf_strategy_t s, char *json, size_t capacity, size_t *required, char *error, size_t error_capacity)
	Part A: the module's outputs manifest, canonical JSON (pineforge-outputs-manifest/v1): what every output, slot and constant means.
int	strategy_signal_safety_receipt (pf_strategy_t s, char *json, size_t capacity, size_t *required, char *error, size_t error_capacity)
	Part A: the module's signal-safety receipt, canonical JSON (pineforge-signal-safety/v1), per output.

Detailed Description

What a module records besides trades, read after a run or between the inputs of a stream (docs/outputs.md).

A module that records declares named series slots, outputs and run constants, and per run writes one row per bar it publishes: a double per slot (NaN = na), events with an optional message, and one value per run constant. Nothing is recorded until strategy_outputs_set_enabled turns recording on, and nothing a run computes depends on it: trades, the report, PF_ABI_VERSION and every hash are what they are with recording off. What a slot, an output or a constant means is in the manifest the module exports (strategy_outputs_manifest).

Part B, the readers, is implemented by the runtime and present in every module built on it; a module that declares nothing answers them as empty. Part A is generated per module and present only in one that records: detect recording with dlsym("strategy_outputs_api_version").

Threading: every strategy_outputs_* call runs on the thread that drives the handle, never during one of its run or stream calls. A NULL handle answers -1 (nothing for a void function).

Macro Definition Documentation

PINEFORGE_HAS_OUTPUTS_V1

#define PINEFORGE_HAS_OUTPUTS_V1   1

Present in a pineforge.h that declares the group.

Definition at line 1889 of file pineforge.h.

PF_OUTPUTS_API_VERSION

#define PF_OUTPUTS_API_VERSION   1u

What strategy_outputs_api_version answers.

Definition at line 1891 of file pineforge.h.

Enumeration Type Documentation

pf_output_phase_t

enum pf_output_phase_t

The run phase an event was recorded in.

Enumerator
PF_OUTPUT_PHASE_BATCH	a batch run
PF_OUTPUT_PHASE_WARMUP	a stream's warm-up, inside strategy_stream_begin
PF_OUTPUT_PHASE_REALTIME	a stream after its warm-up

Definition at line 1894 of file pineforge.h.

Function Documentation

PF_STATIC_ASSERT()

PF_STATIC_ASSERT

(

sizeof(pf_output_phase_t)

= =4

)

strategy_outputs_set_enabled()

int strategy_outputs_set_enabled	(	pf_strategy_t	s,
		int	on )

Turn recording on (on nonzero) or off.

A change clears the record; a call that changes nothing changes nothing, even while a run is in progress. Returns 0, or -1 with nothing changed and the refusal recorded as code outputs_rejected: reason not_declared, "outputs: this module declares no outputs" (turning on a module that records nothing; turning it off answers 0), or reason run_in_progress, "outputs: recording cannot change during a run" (a change while a batch or a stream, from strategy_stream_begin to strategy_stream_end, is running). As with strategy_set_trace_enabled, a success leaves strategy_get_last_error and its code as they were; a refusal keeps a failed run's own.

References PF_API.

strategy_outputs_series_count()

int strategy_outputs_series_count

(

pf_strategy_t

s

)

Series slots per row; 0 while recording is off.

References PF_API.

strategy_outputs_bars_len()

int64_t strategy_outputs_bars_len

(

pf_strategy_t

s

)

Rows recorded: one per bar the module published this run.

A module that opens at most one row per calculation, as a generated one does, never records more than strategy_script_bars_processed.

References PF_API.

strategy_outputs_bar_times_copy()

int strategy_outputs_bar_times_copy	(	pf_strategy_t	s,
		int64_t	from_bar,
		int64_t *	open_ms,
		int64_t *	close_ms,
		int64_t	capacity,
		int64_t *	written )

Copy the open and close times (Unix ms) of rows from from_bar on.

Requires 0 <= from_bar <= rows, capacity >= 0 and written; either array may be NULL. Writes min(capacity, rows - from_bar) items, sets *written to that count and returns 0; otherwise -1 and nothing written.

References PF_API.

strategy_outputs_series_copy()

int strategy_outputs_series_copy	(	pf_strategy_t	s,
		int	series,
		int64_t	from_bar,
		double *	out,
		int64_t	capacity,
		int64_t *	written )

Copy one slot's values (NaN = na) of rows from from_bar on, as strategy_outputs_bar_times_copy does; out is required when capacity > 0, and series must be below the series count.

References PF_API.

strategy_outputs_events_len()

int strategy_outputs_events_len

(

pf_strategy_t

s

)

Events queued since the run began or since the last clear.

References PF_API.

strategy_outputs_event_get()

int strategy_outputs_event_get	(	pf_strategy_t	s,
		int	index,
		void *	out,
		size_t	size_in )

Copy event index into out: min(size_in, sizeof(pf_output_event_v1_t)) bytes, so an older or newer caller's struct works.

Returns 0, or -1 with nothing written for an index out of range, a NULL out, or a size_in below the 8 bytes of struct_version and size.

References PF_API.

strategy_outputs_events_clear()

void strategy_outputs_events_clear

(

pf_strategy_t

s

)

Drop the queued events, in every mode; rows and the sequence are kept.

A streaming caller clears after strategy_stream_begin and after each input it has read; a batch caller need not clear.

References PF_API.

strategy_outputs_constants_copy()

int strategy_outputs_constants_copy	(	pf_strategy_t	s,
		double *	out,
		int	capacity )

Copy the run constants (NaN = na, or not written this run) into out: the first min(capacity, n) of them.

Returns n, the declared count (0 while recording is off), or -1 for capacity < 0 or a NULL out with capacity > 0.

References PF_API.

strategy_outputs_api_version()

uint32_t strategy_outputs_api_version

(

void

)

Part A: PF_OUTPUTS_API_VERSION.

Present only in a module that records.

References PF_API.

strategy_outputs_manifest()

int strategy_outputs_manifest	(	pf_strategy_t	s,
		char *	json,
		size_t	capacity,
		size_t *	required,
		char *	error,
		size_t	error_capacity )

Part A: the module's outputs manifest, canonical JSON (pineforge-outputs-manifest/v1): what every output, slot and constant means.

The buffer and status protocol of strategy_capabilities_receipt.

References PF_API.

strategy_signal_safety_receipt()

int strategy_signal_safety_receipt	(	pf_strategy_t	s,
		char *	json,
		size_t	capacity,
		size_t *	required,
		char *	error,
		size_t	error_capacity )

Part A: the module's signal-safety receipt, canonical JSON (pineforge-signal-safety/v1), per output.

The protocol of strategy_capabilities_receipt.

References PF_API.