|
PineForge unreleased
Deterministic PineScript v6 backtest runtime — C ABI reference
|
#include <pineforge/pineforge.h>Go to the source code of this file.
Data Structures | |
| struct | pf_report_sink_v1 |
| Path sink descriptor (DESIGN 6:1283-1289, 1307-1309). More... | |
| struct | pf_report_sink_fd_v1 |
| Borrowed sequential stream sink descriptor (CX-SINK-B1/B2). More... | |
| struct | pf_report_sink_receipt_v1 |
| Trailer receipt (DESIGN 6:1291-1298,1305-1306). More... | |
| struct | pf_report_sink_summary_v1 |
| Report-only T-row summary (CX-SINK-B5a), independent of the 144-byte trailer receipt above. More... | |
| struct | pf_report_sink_diagnostics_v1 |
| Fixed-size annualization provenance from the emitted v1 records. More... | |
| PF_STATIC_ASSERT | ( | sizeof(pf_report_sink_receipt_v1) | = =144 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_receipt_v1, count_e) | = =8 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_receipt_v1, sha256_hex) | = =64 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_receipt_v1, reserved) | = =129 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_receipt_v1, complete) | = =136 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_receipt_v1, trades_retained) | = =140 | ) |
| PF_STATIC_ASSERT | ( | sizeof(pf_report_sink_summary_v1) | = =64 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, struct_size) | = =0 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, version) | = =4 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, count_t) | = =8 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, wins) | = =16 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, losses) | = =24 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, best_trade) | = =32 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, worst_trade) | = =40 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, max_drawdown) | = =48 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, nonfinite_t_field) | = =56 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_summary_v1, complete) | = =60 | ) |
| PF_STATIC_ASSERT | ( | alignof(pf_report_sink_summary_v1) | = =8 | ) |
| PF_STATIC_ASSERT | ( | sizeof(pf_report_sink_diagnostics_v1) | = =72 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_diagnostics_v1, count_e) | = =8 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_diagnostics_v1, first) | = =16 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_diagnostics_v1, last) | = =40 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_diagnostics_v1, trade_at_start) | = =64 | ) |
| PF_STATIC_ASSERT | ( | offsetof(pf_report_sink_diagnostics_v1, complete) | = =68 | ) |
| uint32_t pf_report_sink_version | ( | void | ) |
Returns report sink ABI version 1 (DESIGN 6:1300).
References PF_API.
| int strategy_set_report_sink_v1 | ( | pf_strategy_t | , |
| const pf_report_sink_v1 * | ) |
Install, replace or remove (NULL descriptor) the sink (6:1301, 1307-1309).
Returns 0 accepted; -1 bad struct_size, version, path or handle, or invalid environment arena; -2 stream running/beginning; -3 run in progress or removal while an ordinary run's scratch curve is live. Strings are copied. A refused removal keeps the sink and its summary report unchanged; it never restores a full curve array from scratch. Sealed trade rows (ledger base > 0) also refuse removal with -3 and set_trade_history_streamable(false) with coded logic_error engine_invariant, preserving the sink, receipt and report without rehydrating rows until a new run begin clears size/base to 0 (ordinary scratch ownership still independently refuses removal). Completed fd generations allow NULL through either setter to detach the next-run sink while preserving their receipt, summary and borrowed fd. The sink composes with the execution observer and selected window. Write errors fail the run with the sink I/O code planned for docker/run_failure_codes.json (DESIGN 3.7:881-888; 6:1330-1332). With a sink, pf_report_t contains summary scalars, total_trades and metrics; trades, equity_curve, broker_state_hash and trace are NULL with length 0. Thus total_trades need not equal trades_len, and equity/hash lengths need not equal script_bars_processed (6:1312-1317). Counts and SHA-256 come from the receipt. Without a sink the existing entry points and report behavior stay unchanged (6:1352-1354). A non-NULL descriptor attaches the environment arena if configured: PF_SCRATCH_ARENA_FD=5 and positive PF_SCRATCH_ARENA_BYTES, with validation passing. The first successful attach sets SIGXFSZ to SIG_IGN process-wide; the prior disposition is not restored. Same fd/size reattaches are no-ops. Hosts relying on their SIGXFSZ handler or default termination must account for this before attaching.
References PF_API.
| int strategy_set_report_sink_fd_v1 | ( | pf_strategy_t | , |
| const pf_report_sink_fd_v1 * | ) |
Install, replace or remove (NULL) the single sink using a borrowed fd.
Mutually exclusive with strategy_set_report_sink_v1: either setter replaces the other kind. NULL through either setter removes next-run configuration only when the generation guards permit it. Returns 0 accepted; -1 bad handle, struct_size, version, negative fd or invalid environment arena; -2 stream running/beginning; -3 run in progress or removal of a scratch-backed or sealed-base generation, as the path setter. A successfully completed fd generation permits NULL through either setter to detach next-run configuration while preserving its receipt, summary and borrowed fd. Path generations have no completed-generation detach: their scratch/base guards still apply. A refusal preserves the generation. Descriptor I/O/type and installed device/inode identity are checked at each run begin; a closed, replaced or non-stream descriptor fails the run with report_sink_failed. A host that dup2s a fresh FIFO onto the same descriptor number for the next run must install the sink again. Summary reports and strategy_report_sink_receipt_v1 follow the path sink rules. A non-NULL descriptor attaches the environment arena if configured: PF_SCRATCH_ARENA_FD=5 and positive PF_SCRATCH_ARENA_BYTES, with validation passing. The first successful attach sets SIGXFSZ to SIG_IGN process-wide; the prior disposition is not restored. Same fd/size reattaches are no-ops. Hosts relying on their SIGXFSZ handler or default termination must account for this before attaching.
References PF_API.
| int strategy_report_sink_receipt_v1 | ( | pf_strategy_t | , |
| pf_report_sink_receipt_v1 * | ) |
Query the sink receipt (DESIGN 6:1302; RESOLVED S1).
CORE-TOP's rev 6 amendment (10-18 16:04) uses the observation query strategy_execution_observation_v1 in execution_observer.h as its model. The caller first sets out->struct_size and out->version.
Returns 0 with the receipt filled; -1 with *out unchanged for a bad handle, struct_size or version. With no sink installed, returns 0 with all counts 0, sha256_hex "", complete 0.
Failed, refused, aborted or truncated runs have no valid trailer (3.7:791-793); a receipt without completion is not a valid sink.
References PF_API.
| int strategy_report_sink_summary_v1 | ( | pf_strategy_t | , |
| pf_report_sink_summary_v1 * | ) |
Query the T-row summary for either the path or fd sink.
Initialize out->struct_size to sizeof(*out), out->version to 1. Returns 0 filled; -1 with *out unchanged for NULL out, bad handle, struct_size or version, exactly as strategy_report_sink_receipt_v1. No sink, an unstarted run, failure or abort yields zero values and complete 0. After successful report capture, count_t equals the trailer's count_t and complete is 1. A nonzero nonfinite_t_field must be rejected by consumers as report_result_invalid{field:"trades.<name>", reason:"nonfinite"} before using the summary. Queries never capture a report, read a sink, or advance the fold; repeated reads return the same value. Replacement/removal and new runs reset it.
References PF_API.