|
PineForge v0.13.1-379-g9b50973
Deterministic PineScript v6 backtest runtime — C ABI reference
|
The C host's strategy logic. More...
#include <native_c_api.h>
Data Fields | |
| uint32_t | struct_size |
| sizeof(pf_native_callbacks_v1). | |
| uint32_t | version |
| PF_NATIVE_API_VERSION. | |
| void * | user |
| Opaque; handed back unchanged. | |
| int(* | on_run_begin )(void *user) |
| int(* | on_input )(void *user, const pf_bar_t *bar, int32_t input_index, int32_t completes_script_interval) |
| int(* | on_bar_open )(void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at) |
| int(* | on_bar )(void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at) |
| int(* | on_tick )(void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at) |
| int(* | on_applied )(void *user, const pf_native_applied_v1 *applied, const pf_native_decision_v1 *at) |
| int(* | on_timeframe_bar )(void *user, const pf_bar_t *bar, uint32_t subscription, uint32_t completion, int64_t delivered_at_ms) |
| int(* | on_margin_call )(void *user, const pf_native_event_v1 *margin_call) |
| int(* | on_recalculate )(void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at, uint32_t reason, const pf_native_applied_v1 *cause) |
EVERY calculation of the run, including the script bar's own close — on_native_recalculate. | |
| int(* | on_sub_bar )(void *user, const pf_bar_t *sub, const pf_native_decision_v1 *at) |
One completed lower-timeframe sub-bar of a run that retains a lower feed — on_native_sub_bar. | |
| int(* | on_margin_requirement )(void *user, const pf_native_margin_view_v1 *view, pf_native_margin_decision_v1 *out) |
The two numbers one check point is about to compare — resolve_margin_requirement. | |
| int(* | on_margin_check )(void *user, const pf_native_margin_view_v1 *at, int32_t *allowed) |
Whether this kernel check point is one the host's broker model shares — margin_check_allowed. | |
| int(* | on_margin_call_units )(void *user, const pf_native_margin_view_v1 *view, double *units) |
The size of a kernel-issued liquidation, before it rests — resolve_margin_call_units. | |
| int(* | on_lot_excursion )(void *user, const pf_native_lot_excursion_v1 *facts, double *favorable, double *adverse) |
The favorable and adverse magnitudes of one closing lot — closed_lot_excursion. | |
| int(* | on_close_units )(void *user, const pf_native_close_view_v1 *view, double *units) |
How many units a host-sized CLOSE takes — the units half of resolve_execution_terms, and the only half this header exposes. | |
The C host's strategy logic.
Every entry may be NULL, which is exactly the C++ default: the kernel does nothing for that hook. user is handed back unchanged to every callback. A callback must never let an exception, a longjmp or any other non-local exit escape.
There are two classes of entry, and they read their return value differently. An OBSERVATION callback — everything down to and including on_sub_bar — returns 0 to continue; any other value ends the run Failed with PF_NATIVE_FAILURE_CALLBACK. An ANSWERING callback — the four margin and excursion hooks at the end — returns a pf_native_answer_t selecting WHOSE answer the kernel uses; every value is in contract, so an answering hook can never fail the run. That split is deliberate: the answering hooks are consulted from kernel paths that are not inside the callback guard, so a failure raised there could not be latched without unwinding through them. A host that must abort does it from an observation callback.
Commands are legal inside on_bar_open, on_bar, on_tick and on_applied. on_run_begin, on_input, on_timeframe_bar and on_margin_call are observation-only: a command there answers PF_NATIVE_E_STATE and changes nothing.
on_bar is also the recalculation hook: with a calculation trigger above BarClose the kernel calls it again at each fill cursor or modeled point, which is exactly what the C++ on_native_recalculate default does.
Definition at line 1272 of file native_c_api.h.
| uint32_t pf_native_callbacks_v1::struct_size |
sizeof(pf_native_callbacks_v1).
Definition at line 1273 of file native_c_api.h.
| uint32_t pf_native_callbacks_v1::version |
PF_NATIVE_API_VERSION.
Definition at line 1274 of file native_c_api.h.
| void* pf_native_callbacks_v1::user |
Opaque; handed back unchanged.
Definition at line 1275 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_run_begin) (void *user) |
Definition at line 1276 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_input) (void *user, const pf_bar_t *bar, int32_t input_index, int32_t completes_script_interval) |
Definition at line 1277 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_bar_open) (void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at) |
Definition at line 1279 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_bar) (void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at) |
Definition at line 1280 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_tick) (void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at) |
Definition at line 1281 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_applied) (void *user, const pf_native_applied_v1 *applied, const pf_native_decision_v1 *at) |
Definition at line 1282 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_timeframe_bar) (void *user, const pf_bar_t *bar, uint32_t subscription, uint32_t completion, int64_t delivered_at_ms) |
Definition at line 1284 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_margin_call) (void *user, const pf_native_event_v1 *margin_call) |
Definition at line 1286 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_recalculate) (void *user, const pf_bar_t *bar, const pf_native_decision_v1 *at, uint32_t reason, const pf_native_applied_v1 *cause) |
EVERY calculation of the run, including the script bar's own close — on_native_recalculate.
reason is a pf_native_calc_reason_t and cause is the applied execution of an ORDER_FILL recalculation, valid only for that call and NULL otherwise. bar is the COMPLETE script bar even mid-path; strategy_native_partial_bar_v1 is the lookahead-free bar so far. Commands are legal here.
Installing it REPLACES on_bar for every calculation, exactly as overriding on_native_recalculate replaces the C++ default forwarding: a host that wants both calls on_bar itself from here. Leaving it NULL keeps the established contract, where the kernel forwards every calculation to on_bar. Observation callback: non-zero ends the run.
Definition at line 1305 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_sub_bar) (void *user, const pf_bar_t *sub, const pf_native_decision_v1 *at) |
One completed lower-timeframe sub-bar of a run that retains a lower feed — on_native_sub_bar.
Delivered after that sub-bar's whole matching path and before the next one's; never called for a run with no retained lower feed. The decision point is the sub-bar's last modeled point, so commands and strategy_native_execute_current_v1 are legal. Observation callback: non-zero ends the run.
Definition at line 1315 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_margin_requirement) (void *user, const pf_native_margin_view_v1 *view, pf_native_margin_decision_v1 *out) |
The two numbers one check point is about to compare — resolve_margin_requirement.
ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to keep the kernel's own, any other value to use out. The kernel keeps the whole mechanism — the level solve, the check points, its own request, the receipt, on_margin_call; this supplies only the money rule brokers legitimately differ on.
Definition at line 1323 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_margin_check) (void *user, const pf_native_margin_view_v1 *at, int32_t *allowed) |
Whether this kernel check point is one the host's broker model shares — margin_check_allowed.
ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to admit the point (the kernel's own answer), any other value to use allowed (0 suppresses it). A suppressed point is not evaluated, re-armed or withdrawn: the margin state is left exactly as the last admitted point left it.
Definition at line 1332 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_margin_call_units) (void *user, const pf_native_margin_view_v1 *view, double *units) |
The size of a kernel-issued liquidation, before it rests — resolve_margin_call_units.
ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to keep the run spec's sizing policy, any other value to use units, which the kernel clamps into (0, held]. It has the last word on units, including over a forced breach.
Definition at line 1339 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_lot_excursion) (void *user, const pf_native_lot_excursion_v1 *facts, double *favorable, double *adverse) |
The favorable and adverse magnitudes of one closing lot — closed_lot_excursion.
Installing it at all is owns_lot_excursions() == true: the consumer then stops sampling excursion at matched trigger prices for the WHOLE run and every closing row takes both magnitudes from here. ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to answer the kernel's own zero magnitudes — which, ownership having been declared, is what a declined lot gets — or any other value to use favorable and adverse.
Definition at line 1350 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_close_units) (void *user, const pf_native_close_view_v1 *view, double *units) |
How many units a host-sized CLOSE takes — the units half of resolve_execution_terms, and the only half this header exposes.
Consulted for PF_NATIVE_INTENT_HOST_SIZED candidates and nothing else; without it a cohort close resolves no quantity and stands deferred, which is exactly what the C++ default does. ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to keep that default, any other value to close units of pf_native_close_view_v1::scope_exposure_units.
Definition at line 1361 of file native_c_api.h.