|
PineForge unreleased
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) |
| One completed bucket of a declared series. | |
| 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 (the price half is on_execution_terms). | |
| int(* | on_execution_terms )(void *user, const pf_native_terms_view_v1 *view, pf_native_terms_v1 *out) |
The price half of resolve_execution_terms, consulted at EVERY matching candidate once installed. | |
| int(* | on_precommit )(void *user, const pf_native_precommit_view_v1 *view, uint32_t *verdict) |
The last gate before one execution's physical effect — validate_execution_precommit. | |
| int(* | on_anchored_level )(void *user, const pf_native_anchored_level_view_v1 *view, double *level) |
Where an anchored leg is armed — resolve_anchored_level. | |
| int(* | on_hash_extension )(void *user, uint64_t *digest) |
The host's own durable state, folded into the broker-state hash — hash_host_extension. | |
| uint64_t | reserved1 |
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 — every hook from on_margin_requirement on — 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 follow the C++ host's callback guard: they are legal in every callback while the kernel is Running, including on_timeframe_bar and on_margin_call. The kernel may still reject a particular request or current-execution action for its own reason. The answering hooks must only answer their question; they run on paths without the callback guard. strategy_native_declare_opened_lot_entry_bar_mask_v1 is legal inside on_applied alone.
on_bar is also the recalculation hook: with a calculation trigger above PF_NATIVE_CALC_TRIGGER_BAR_CLOSE 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 2505 of file native_c_api.h.
| uint32_t pf_native_callbacks_v1::struct_size |
sizeof(pf_native_callbacks_v1).
Definition at line 2506 of file native_c_api.h.
| uint32_t pf_native_callbacks_v1::version |
PF_NATIVE_API_VERSION.
Definition at line 2507 of file native_c_api.h.
| void* pf_native_callbacks_v1::user |
Opaque; handed back unchanged.
Definition at line 2508 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_run_begin) (void *user) |
Definition at line 2509 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 2510 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 2512 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 2513 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 2514 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 2515 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) |
One completed bucket of a declared series.
completion is a pf_native_completion_kind_t: CONFIRMED when the bucket's own last contributing bar closed it, LAZY_COMPLETE when the next period's first input did.
Definition at line 2521 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 2523 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 2541 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 2551 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 2559 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 2568 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 2575 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 2586 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 (the price half is on_execution_terms).
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 2597 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_execution_terms) (void *user, const pf_native_terms_view_v1 *view, pf_native_terms_v1 *out) |
The price half of resolve_execution_terms, consulted at EVERY matching candidate once installed.
ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to keep the kernel's terms, any other value to settle at out's price, shape and grid policy. out arrives holding the kernel's own. A shape or grid word outside its enumeration is the kernel's PF_NATIVE_MATCH_REJECT_INVALID_TERMS, as is a shape other than TRANSACT on anything but an opening. The units half stays on_close_units'.
Definition at line 2613 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_precommit) (void *user, const pf_native_precommit_view_v1 *view, uint32_t *verdict) |
The last gate before one execution's physical effect — validate_execution_precommit.
ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to admit it on the kernel's own path, any other value to use verdict (pf_native_precommit_verdict_t). A verdict word outside the enumeration refuses, the conservative reading of an answer the kernel cannot act on.
Definition at line 2622 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_anchored_level) (void *user, const pf_native_anchored_level_view_v1 *view, double *level) |
Where an anchored leg is armed — resolve_anchored_level.
ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to install the kernel's level, any other value to install level; the kernel's representability check still applies.
Definition at line 2629 of file native_c_api.h.
| int(* pf_native_callbacks_v1::on_hash_extension) (void *user, uint64_t *digest) |
The host's own durable state, folded into the broker-state hash — hash_host_extension.
Called once per hash (every per-bar row, the final and the stream hash) after the kernel's own bytes. ANSWERING callback: return PF_NATIVE_ANSWER_DEFAULT to fold nothing more, any other value to fold a domain tag and digest, a 64-bit digest of whatever the host's next decision depends on. It must be a pure function of that state. The continuation hash is the kernel's alone and does not move.
Definition at line 2640 of file native_c_api.h.
| uint64_t pf_native_callbacks_v1::reserved1 |
Definition at line 2646 of file native_c_api.h.