|
PineForge v0.13.1-379-g9b50973
Deterministic PineScript v6 backtest runtime — C ABI reference
|
#include <stdint.h>#include <stddef.h>#include <pineforge/version.h>#include <pineforge/pending_order_mirror.hpp>#include <pineforge/native_c_api.h>Go to the source code of this file.
Data Structures | |
| struct | pf_bar_t |
| Single OHLCV bar pushed into the engine. More... | |
| struct | pf_trade_tick_t |
| One provider-neutral realtime executed-trade update. More... | |
| struct | pf_trade_t |
| Closed-trade record returned in pf_report_t::trades. More... | |
| struct | pf_trade_stats_t |
| Trade-level statistics block — computed once each for all / long / short. More... | |
| struct | pf_equity_stats_t |
| Equity-curve-derived statistics (all-trades only, like TV). More... | |
| struct | pf_metrics_t |
| Composite metrics container: trade stats (all / long / short) + equity-curve stats. More... | |
| struct | pf_equity_point_t |
| Single per-script-bar equity point. More... | |
| struct | pf_security_diag_t |
Per-request.security() site diagnostic counters. More... | |
| struct | pf_trace_entry_t |
| Single per-bar trace entry. More... | |
| struct | pf_report_t |
| Backtest report filled by run_backtest / run_backtest_full. More... | |
| struct | pf_native_run_spec_v1 |
| Versioned native run specification. More... | |
| struct | pf_native_fx_curve_v1 |
| Immutable timestamped account-currency FX curve for a native run. More... | |
| struct | pf_stream_order_action_t |
| One physical emulator lot action. More... | |
| struct | pf_version_t |
| Runtime version descriptor returned by pf_version_get. More... | |
Macros | |
| #define | PF_API |
| #define | PF_ABI_VERSION 4 |
| Monotonic ABI version of pf_report_t / pf_trade_t layout. | |
| #define | PINEFORGE_HAS_AUX_SECURITY_FEED_V1 1 |
| Feature probe for the opt-in split chart/request.security feed boundary. | |
| #define | PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1 1 |
| Feature probe for native higher-timeframe request.security feeds. | |
| #define | PINEFORGE_HAS_NATIVE_FX_CURVE_V1 1 |
| Feature probe for immutable native-run account-currency FX curves. | |
Typedefs | |
| typedef void * | pf_strategy_t |
| Opaque handle to a compiled strategy instance. | |
Enumerations | |
| enum | pf_magnifier_distribution_t { PF_MAGNIFIER_UNIFORM = 0 , PF_MAGNIFIER_COSINE = 1 , PF_MAGNIFIER_TRIANGLE = 2 , PF_MAGNIFIER_ENDPOINTS = 3 , PF_MAGNIFIER_FRONT_LOADED = 4 , PF_MAGNIFIER_BACK_LOADED = 5 } |
| Bar-magnifier sub-bar sampling distribution. More... | |
Functions | |
| int | strategy_execution_contract (pf_strategy_t s) |
| Native execution contract query. | |
| int | strategy_configure_native_v1 (pf_strategy_t s, const pf_native_run_spec_v1 *spec) |
| Apply a native v1 specification. | |
| int | strategy_configure_native_fx_curve_v1 (pf_strategy_t s, const pf_native_fx_curve_v1 *curve) |
| Stage an immutable account-currency FX curve on a Ready native handle. | |
| pf_strategy_t | strategy_create (const char *params_json) |
| Allocate a new strategy instance. | |
| void | strategy_free (pf_strategy_t s) |
| Release a strategy handle previously returned by strategy_create. | |
| void | run_backtest (pf_strategy_t s, pf_bar_t *bars, int n, pf_report_t *out) |
| Run a backtest with auto-detected timeframe and no bar magnifier. | |
| void | run_backtest_full (pf_strategy_t s, pf_bar_t *bars, int n, const char *input_tf, const char *script_tf, int bar_magnifier, int magnifier_samples, pf_magnifier_distribution_t magnifier_dist, pf_report_t *out) |
| Run a backtest with explicit timeframe and magnifier configuration. | |
| void | report_free (pf_report_t *report) |
| Free heap arrays attached to a filled report. | |
| void | strategy_set_input (pf_strategy_t s, const char *key, const char *value) |
Override a Pine input. | |
| void | strategy_set_override (pf_strategy_t s, const char *key, const char *value) |
Override a strategy(...) declaration parameter. | |
| void | strategy_set_magnifier_volume_weighted (pf_strategy_t s, int on) |
| Toggle volume-weighted bar-magnifier sampling. | |
| void | strategy_set_trace_enabled (pf_strategy_t s, int on) |
| Toggle per-bar trace recording. | |
| void | strategy_set_trade_start_time (pf_strategy_t s, int64_t timestamp_ms) |
| Set the earliest Unix-ms timestamp at which strategy order commands may fire. | |
| uint64_t | strategy_closed_trade_entry_incarnation (pf_strategy_t s, int trade_index) |
| Return the physical entry incarnation for one closed-trade row. | |
| int | strategy_stream_begin (pf_strategy_t s, const pf_bar_t *warmup_bars, int n_warmup, const char *input_tf, const char *script_tf) |
| Warm a strategy with confirmed OHLCV, then switch the same instance to a realtime trade stream without resetting position, equity, pending orders, Pine variables, TA state, request.security state, or timeframe aggregation. | |
| int | strategy_stream_api_version (void) |
| Native live extension version (1). | |
| int | strategy_stream_push_bar (pf_strategy_t s, const pf_bar_t *bar) |
| Consume one confirmed input-timeframe bar. | |
| int | strategy_stream_order_actions_len (pf_strategy_t s) |
| Queued physical fills since the last clear, in execution order. | |
| int | strategy_stream_order_action_get (pf_strategy_t s, int index, pf_stream_order_action_t *out) |
| Copy one action; return 0 on success, -1 on invalid handle/index/output. | |
| void | strategy_stream_order_actions_clear (pf_strategy_t s) |
| Clear observed events after the caller durably journals them. | |
| uint64_t | strategy_stream_state_hash (pf_strategy_t s) |
| Versioned deterministic fingerprint of observable broker/stream state. | |
| int | strategy_stream_push_tick (pf_strategy_t s, const pf_trade_tick_t *tick) |
| Push one normalized realtime trade. | |
| int | strategy_stream_push_ticks (pf_strategy_t s, const pf_trade_tick_t *ticks, int n) |
| Push an ordered batch of realtime trades. | |
| int | strategy_stream_advance_time (pf_strategy_t s, int64_t timestamp_ms) |
| Advance the stream clock and close every input bar whose end is <= the supplied time. | |
| int | strategy_stream_end (pf_strategy_t s, int finalize_partial_input_bar) |
| End a realtime stream. | |
| int | strategy_stream_fill_report (pf_strategy_t s, pf_report_t *out) |
| Snapshot the cumulative warmup + realtime report. | |
| void | strategy_request_abort (pf_strategy_t s) |
| Request cooperative abort of the run in progress (see c_abi.cpp). | |
| int | strategy_last_run_status (pf_strategy_t s) |
0 = completed, 1 = NOT_COMPLETED (aborted), -1 = s is NULL. | |
| void | strategy_set_realtime_tail (pf_strategy_t s, int on, int horizon_bars) |
| Live-runtime tail semantics (spec §3.1): the LAST bar of the array fed to every subsequent run() is a still-forming bar, not the chart's rightmost historical bar. | |
| void | strategy_set_probe_suppress_tail_logic (pf_strategy_t s, int on) |
Live probe tail suppression (spec §3.2): the LAST bar of the array fed to every subsequent run() runs only the broker's pre-on_bar steps and returns, in this order: intraday-cap deferred close, advancing native source-series history (_push_source_series), settling resting stop/limit orders against the bar (native request matching), the max-intraday-loss path check (evaluate_max_intraday_loss_over_path), and updating per-trade extremes (update_per_trade_extremes). | |
| void | strategy_set_path_order (pf_strategy_t s, int mode) |
Force this run's intrabar path order (ABI v4 live-runtime surface): the leg order every OHLC-path helper (bar_path_uses_high_first and everything built on it – stop/limit fill priority, exit trail walking, dual-entry-stop arbitration, and bar-magnifier sub-bar sampling) uses for the CURRENT and every subsequent run(), until a caller sets a different mode. | |
| int | strategy_last_bar_dual_entry_path (pf_strategy_t s) |
The dual-entry-stop arbitration decided on the LAST bar the most recent run() dispatched: a flat position resting exactly one long stop-only ENTRY and one short stop-only ENTRY, both touched on that bar (dual_entry_stop_path_winner, internal). | |
| void | strategy_set_broker_state_hash_recording (pf_strategy_t s, int on) |
| Toggle per-script-bar broker-state hash recording (spec §3.4, ABI v4). | |
| uint64_t | strategy_broker_state_hash (pf_strategy_t s) |
| Return the broker-state hash of the FINAL state after the most recent run() (see strategy_set_broker_state_hash_recording's doc and pf_report_t::broker_state_hash for the per-bar recording; this accessor works whether or not recording was enabled). | |
| int | strategy_pending_orders_len (pf_strategy_t s) |
| Number of orders resting in the engine's pending-order book after the most recent run() (ABI v4 live-runtime surface, task 7, spec 3.6): the book in force for the NEXT bar. | |
| int | strategy_pending_order_get (pf_strategy_t s, int index, void *out, size_t size_in) |
Copy the index-th resting order (0-based, the engine's own book order – insertion order; broker fill priority is decided at fill time from created_seq, not from this index) into out as a pf_pending_order_v1_t value snapshot. | |
| const pf_field_desc_t * | strategy_pending_order_layout (int *count) |
The field table of pf_pending_order_v1_t as THIS runtime compiled it – one pf_field_desc_t {name, type, offset, size} per field, in struct order, starting with struct_version and size. | |
| int | strategy_pending_order_fill_qty (pf_strategy_t s, int index, double fill_price, double *qty, int *close_only, int *partition) |
Engine-computed fill quantity of the index-th resting order (ABI v4 live-runtime surface, task 8, spec 3.6): the contracts the entry kernel would OPEN if that order filled at fill_price, sized by the engine's own rules so a live runtime never re-implements them. | |
| int | strategy_pending_order_level_resolved (pf_strategy_t s, int index) |
1 when the index-th resting order's entry-relative offsets (profit_ticks / loss_ticks / trail_points) resolve now (ABI v4, task 8): entries, plain orders and exits with an empty from_entry always; an exit bound to a from_entry only once that id has filled in the CURRENT position cycle – the gate the engine's own materialize_relative_exit_prices_for_live_position and eligibility pass share. | |
| int | strategy_pending_order_effective_levels (pf_strategy_t s, int index, double *stop, double *limit, double *trail_activation) |
The price levels the index-th resting order would fire at, as the engine's fill path resolves them (ABI v4, task 8). | |
| double | strategy_trail_best_price (pf_strategy_t s) |
The trail extreme the exit trail legs ride (trail_best_price_: the running high of a long / low of a short since the position filled, bar extremes folded in as the fill path folds them). | |
| double | strategy_position_avg_price (pf_strategy_t s) |
The live position's volume-weighted average entry price (position_entry_price_). | |
| int64_t | strategy_position_cycle_seq (pf_strategy_t s) |
The live position's cycle id (position_cycle_seq_): 0 when flat, a fresh nonzero id per open or reversal, unchanged across same-direction adds – the id created_position_cycle_seq on a mirrored order refers to. | |
| const char * | strategy_closed_trade_entry_id (pf_strategy_t s, int trade_index) |
Task 9: closed-trade id / exit-comment string accessors, indexing the same REPORT row space as strategy_closed_trade_entry_incarnation (trades_ then the range-end rows, open_at_end). | |
| const char * | strategy_closed_trade_exit_id (pf_strategy_t s, int trade_index) |
| See strategy_closed_trade_entry_id for the row-space/lifetime/NULL contract. | |
| const char * | strategy_closed_trade_exit_comment (pf_strategy_t s, int trade_index) |
| See strategy_closed_trade_entry_id. | |
| int | strategy_closed_trade_close_cause (pf_strategy_t s, int trade_index) |
Task 9: why the trade_index-th REPORT-row closed trade exited. | |
| double | strategy_position_size (pf_strategy_t s) |
Task 9: the script-facing signed position size (strategy.position_size; KI-64 freeze-aware – while a same-bar process_orders_on_close close is frozen for the current bar, this reads the PRE-close position, matching what the script itself observes). | |
| double | strategy_current_equity (pf_strategy_t s) |
Task 9: initial capital plus realized net profit (strategy.initial_capital + strategy.netprofit). | |
| int64_t | strategy_script_bars_processed (pf_strategy_t s) |
Task 9: total SCRIPT bars dispatched by the most recent run() (mirrors pf_report_t::script_bars_processed, engine_report.cpp) – includes a stream's warmup leg and every realtime tick-driven bar dispatched afterward by strategy_stream_push_tick / strategy_stream_push_ticks. | |
| void | strategy_set_chart_timezone (pf_strategy_t s, const char *tz) |
| Set the strategy's chart timezone (IANA / POSIX TZ string). | |
| void | strategy_set_syminfo_timezone (pf_strategy_t s, const char *tz) |
| Plumb the symbol's exchange timezone (IANA string) into syminfo. | |
| void | strategy_set_syminfo_session (pf_strategy_t s, const char *session) |
| Set the symbol's session string (e.g. | |
| void | strategy_set_syminfo_type (pf_strategy_t s, const char *type) |
Set the instrument class (syminfo.type: "forex", "stock", "crypto", "futures", "index", "fund", "cfd", ...; default "crypto"). | |
| int | strategy_set_syminfo_string (pf_strategy_t s, const char *key, const char *value) |
Set one of the remaining string members of syminfo by Pine member name: "ticker", "tickerid", "currency", "basecurrency", "description", "volumetype" (and "type"). | |
| void | strategy_set_syminfo_mintick (pf_strategy_t s, double mintick) |
Set the instrument tick size (syminfo.mintick, default 0.01). | |
| void | strategy_set_syminfo_pointvalue (pf_strategy_t s, double pointvalue) |
Set the instrument point value (syminfo.pointvalue, default 1.0) — the $-per-point-per-contract multiplier applied to every money path: realized PnL and MFE/MAE, open profit / mark-to-market equity (and the drawdown / runup extremes), percent-of-equity and cash position sizing, percent commission notionals, and the margin admission check. | |
| void | strategy_set_syminfo_metadata (pf_strategy_t s, const char *key, double value) |
| Inject a fundamental/exchange metadata value by Pine member name (e.g. | |
| int | strategy_set_account_currency_fx_series (pf_strategy_t s, const int64_t *effective_from_ms, const double *account_per_quote, int n) |
| Install a timestamped quote-to-account currency conversion curve. | |
| int | strategy_set_aux_security_feed (pf_strategy_t s, const pf_bar_t *bars, int n, const char *input_tf) |
| Copy a finer feed used exclusively by same-symbol request.security calls. | |
| int | strategy_set_native_security_feed (pf_strategy_t s, const char *timeframe, const pf_bar_t *bars, int n) |
| Copy the exchange's OWN bars of one higher timeframe for same-symbol request.security calls that request exactly that timeframe. | |
| const char * | strategy_get_last_error (pf_strategy_t s) |
| Returns the error message captured by the most recent run_backtest / run_backtest_full call on this strategy. | |
| pf_version_t | pf_version_get (void) |
| int | pf_abi_version (void) |
| const char * | pf_version_string (void) |
| Full git-derived version descriptor. | |
| #define PF_API |
Definition at line 70 of file pineforge.h.
Referenced by native_market_example_abi_version(), native_selected_example_failure_code(), native_selected_example_failure_discriminator(), native_selected_example_host_epoch(), native_selected_example_host_sized_applied(), native_selected_example_host_sized_opened_units(), native_selected_example_lifecycle(), native_selected_example_reversal_applied(), native_selected_example_reversal_opened_units(), native_selected_example_reversal_terminal_kind(), native_selected_example_selected_applied(), native_selected_example_selected_ticket(), pf_abi_version(), pf_version_get(), pf_version_string(), report_free(), run_backtest(), run_backtest_full(), strategy_broker_state_hash(), strategy_closed_trade_close_cause(), strategy_closed_trade_entry_id(), strategy_closed_trade_entry_incarnation(), strategy_closed_trade_exit_comment(), strategy_closed_trade_exit_id(), strategy_configure_native_ext_v1(), strategy_configure_native_fx_curve_v1(), strategy_configure_native_v1(), strategy_create(), strategy_current_equity(), strategy_execution_contract(), strategy_free(), strategy_get_last_error(), strategy_last_bar_dual_entry_path(), strategy_last_run_status(), strategy_native_api_version(), strategy_native_append_auxiliary_bars_v1(), strategy_native_cancel_all_v1(), strategy_native_cancel_v1(), strategy_native_cancel_where_v1(), strategy_native_cohort_add_v1(), strategy_native_cohort_open_v1(), strategy_native_cohort_remove_v1(), strategy_native_continuation_hash_v1(), strategy_native_declare_subscriptions_v1(), strategy_native_events_v1(), strategy_native_execute_current_v1(), strategy_native_host_create_v1(), strategy_native_host_free(), strategy_native_liquidation_price_v1(), strategy_native_marked_equity_v1(), strategy_native_open_lot_count_v1(), strategy_native_open_lot_get_v1(), strategy_native_partial_bar_v1(), strategy_native_position_v1(), strategy_native_recalculations_v1(), strategy_native_replace_v1(), strategy_native_report_free_v1(), strategy_native_risk_state_v1(), strategy_native_run_v1(), strategy_native_series_bar_v1(), strategy_native_state_v1(), strategy_native_submit_v1(), strategy_native_trail_state_v1(), strategy_native_working_get_v1(), strategy_native_working_len_v1(), strategy_pending_order_effective_levels(), strategy_pending_order_fill_qty(), strategy_pending_order_get(), strategy_pending_order_layout(), strategy_pending_order_level_resolved(), strategy_pending_orders_len(), strategy_position_avg_price(), strategy_position_cycle_seq(), strategy_position_size(), strategy_request_abort(), strategy_script_bars_processed(), strategy_set_account_currency_fx_series(), strategy_set_aux_security_feed(), strategy_set_broker_state_hash_recording(), strategy_set_chart_timezone(), strategy_set_input(), strategy_set_magnifier_volume_weighted(), strategy_set_native_security_feed(), strategy_set_override(), strategy_set_path_order(), strategy_set_probe_suppress_tail_logic(), strategy_set_realtime_tail(), strategy_set_syminfo_metadata(), strategy_set_syminfo_mintick(), strategy_set_syminfo_pointvalue(), strategy_set_syminfo_session(), strategy_set_syminfo_string(), strategy_set_syminfo_timezone(), strategy_set_syminfo_type(), strategy_set_trace_enabled(), strategy_set_trade_start_time(), strategy_stream_advance_time(), strategy_stream_api_version(), strategy_stream_begin(), strategy_stream_end(), strategy_stream_fill_report(), strategy_stream_order_action_get(), strategy_stream_order_actions_clear(), strategy_stream_order_actions_len(), strategy_stream_push_bar(), strategy_stream_push_tick(), strategy_stream_push_ticks(), strategy_stream_state_hash(), and strategy_trail_best_price().
| #define PF_ABI_VERSION 4 |
Monotonic ABI version of pf_report_t / pf_trade_t layout.
Bumped whenever a caller-visible struct grows. Consumers MUST verify pf_abi_version() == PF_ABI_VERSION before calling run_backtest. pf_report_t is caller-allocated: growth causes silent stack corruption in old callers that under-size the struct. pf_trade_t is runtime- allocated: growth causes array-stride misindexing in old readers that iterate the trades array with the stale sizeof. Value 2 = first versioned layout (metrics + equity curve); .so files predating this macro have no pf_abi_version symbol — treat dlsym failure as version 1. Value 3 appends pf_trade_t::open_at_end (the range-end close flag); a v2 reader iterating trades with the v2 stride would misindex every row after the first. Value 4 appends the live-runtime accessors and the per-bar broker-state hash array to pf_report_t.
Definition at line 86 of file pineforge.h.
| #define PINEFORGE_HAS_AUX_SECURITY_FEED_V1 1 |
Feature probe for the opt-in split chart/request.security feed boundary.
When defined, strategy_set_aux_security_feed is available.
Definition at line 90 of file pineforge.h.
| #define PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1 1 |
Feature probe for native higher-timeframe request.security feeds.
When defined, strategy_set_native_security_feed is available.
Definition at line 94 of file pineforge.h.
| #define PINEFORGE_HAS_NATIVE_FX_CURVE_V1 1 |
Feature probe for immutable native-run account-currency FX curves.
When defined, strategy_configure_native_fx_curve_v1 is available.
Definition at line 98 of file pineforge.h.
| typedef void* pf_strategy_t |
Opaque handle to a compiled strategy instance.
Definition at line 433 of file pineforge.h.