|
PineForge unreleased
Deterministic PineScript v6 backtest runtime — C ABI reference
|
Functions | |
| int | strategy_native_api_version (void) |
| This header's layout version. | |
| pf_strategy_t | strategy_native_host_create_v1 (const pf_native_callbacks_v1 *callbacks) |
Allocate a native host that forwards every kernel callback to callbacks. | |
| void | strategy_native_host_free (pf_strategy_t s) |
| Release a handle from strategy_native_host_create_v1. | |
| int | strategy_native_run_v1 (pf_strategy_t s, const pf_bar_t *bars, int n, pf_report_t *out) |
Run n bars as one batch and fill out. | |
| void | strategy_native_report_free_v1 (pf_report_t *report) |
| Free the heap arrays inside a report filled by strategy_native_run_v1. | |
| int | strategy_native_submit_v1 (pf_strategy_t s, const pf_native_request_v1 *request, uint64_t *incarnation, uint32_t *reject) |
Submit request. | |
| int | strategy_native_replace_v1 (pf_strategy_t s, uint64_t incarnation, const pf_native_request_v1 *request, uint64_t *successor) |
Replace the live request incarnation with request. | |
| int | strategy_native_replace_ext_v1 (pf_strategy_t s, uint64_t incarnation, const pf_native_request_v1 *request, uint64_t *successor, uint32_t *reject) |
Replace the live request incarnation, reporting a rejection's reason. | |
| int | strategy_native_cancel_v1 (pf_strategy_t s, uint64_t incarnation) |
| Cancel one live request. | |
| int | strategy_native_cancel_all_v1 (pf_strategy_t s) |
| Cancel every live request, dependants included. | |
| int | strategy_native_cancel_where_v1 (pf_strategy_t s, const char *text, uint32_t field) |
Cancel exactly the live requests whose field equals text. | |
| int | strategy_native_execute_current_v1 (pf_strategy_t s, uint64_t incarnation, uint32_t price_rule, uint32_t *refusal) |
| Execute one live request at the current execution point. | |
| int | strategy_native_position_v1 (pf_strategy_t s, double *signed_units, double *average_price, uint64_t *lots) |
| Read the physical position. | |
| int | strategy_native_working_len_v1 (pf_strategy_t s) |
| Snapshot the live working book and return its length. | |
| int | strategy_native_working_get_v1 (pf_strategy_t s, int index, pf_native_working_v1 *out) |
Copy row index of the most recent working snapshot into out. | |
| int | strategy_native_open_lot_count_v1 (pf_strategy_t s, double mark) |
Snapshot the open lots marked at mark and return their count. | |
| int | strategy_native_open_lot_get_v1 (pf_strategy_t s, int index, pf_native_open_lot_v1 *out) |
Copy row index of the most recent open-lot snapshot into out. | |
| int | strategy_native_events_v1 (pf_strategy_t s, uint64_t after_ordinal, pf_native_event_v1 *out, int cap) |
Copy up to cap events with an ordinal strictly greater than after_ordinal into out, in the kernel's own recording order. | |
| int | strategy_native_acknowledge_events_v1 (pf_strategy_t s, uint64_t through_ordinal) |
The host has read every event through through_ordinal — native_acknowledge_events(). | |
| int | strategy_native_event_window_v1 (pf_strategy_t s, uint64_t *out_first_ordinal) |
The oldest ordinal a read can still return — native_event_window_start() — written to out_first_ordinal: every command event at or above it is retained, and strategy_native_events_v1 with an after_ordinal below it starts there. | |
| int | strategy_native_state_v1 (pf_strategy_t s, pf_native_state_v1 *out) |
Read the run's lifecycle and typed failure into out. | |
| int | strategy_native_declare_subscriptions_v1 (pf_strategy_t s, const pf_native_subscription_v1 *rows, int n) |
Declare this run's higher-timeframe series from inside on_run_begin — declare_timeframe_subscriptions(). | |
| int | strategy_native_declare_subscriptions_ext_v1 (pf_strategy_t s, const pf_native_subscription_v1 *rows, int n, const uint32_t *sources, uint32_t *error, uint32_t *field) |
The same declaration, answered by name — declare_timeframe_subscriptions_result(). | |
| int | strategy_native_declare_auxiliary_feed_v1 (pf_strategy_t s, const char *tf, const pf_bar_t *bars, int32_t n, uint32_t *error, uint32_t *field) |
Declare, replace or withdraw this run's auxiliary finer feed from inside on_run_begin — declare_auxiliary_feed_result(). | |
| int | strategy_native_partial_bar_v1 (pf_strategy_t s, pf_bar_t *out) |
The bar so far — current_partial_bar(). | |
| int | strategy_native_recalculations_v1 (pf_strategy_t s, uint64_t *driven, uint64_t *skipped) |
How many recalculations the kernel drove, and how many it suppressed because a point had spent its max_recalculations_per_point budget — native_recalculation_count() / native_recalculations_skipped(). | |
| int | strategy_native_trail_state_v1 (pf_strategy_t s, uint64_t incarnation, pf_native_trail_state_v1 *out) |
The trail projection of one live request — trail_state(). | |
| int | strategy_native_series_bar_v1 (pf_strategy_t s, uint32_t subscription, pf_bar_t *out) |
The latest completed bucket of a declared subscription — native_series_bar(). | |
| int | strategy_native_timeframe_bar_interval_v1 (pf_strategy_t s, pf_native_timeframe_interval_v1 *out) |
| Read the delivered bucket's own calendar interval from inside pf_native_callbacks_v1::on_timeframe_bar. | |
| int | strategy_native_marked_equity_v1 (pf_strategy_t s, double mark, double *out) |
The account's marked equity at mark — native_marked_equity(). | |
| int | strategy_native_liquidation_price_v1 (pf_strategy_t s, double *out) |
The price at which the marked equity falls below the run's maintenance requirement for the live position's side — native_liquidation_price(). | |
| int | strategy_native_sized_units_v1 (pf_strategy_t s, const pf_native_request_v1 *sized, double price, double equity, double fx, double *units) |
The units a kernel-sized request resolves to under this run's spec, as a pure query — native_sized_units(). | |
| int | strategy_native_risk_state_v1 (pf_strategy_t s, pf_native_risk_state_v1 *out) |
The run's generic risk ledger — native_risk_state(). | |
| int | strategy_native_margin_call_v1 (pf_strategy_t s, uint64_t ordinal, pf_native_margin_call_v1 *out) |
The whole economics of one margin call — what a C++ host's on_native_margin_call receives as MarginCallEvent. | |
| int | strategy_native_continuation_hash_v1 (pf_strategy_t s, uint64_t *out) |
The run's continuation identity — native_continuation_hash(). | |
| int | strategy_native_cohort_open_v1 (pf_strategy_t s, uint64_t *cohort) |
| Open a cohort roster for PF_NATIVE_OWNER_BIND_COHORT. | |
| int | strategy_native_cohort_add_v1 (pf_strategy_t s, uint64_t cohort, uint64_t incarnation) |
| Enrol a live request into a cohort roster. | |
| int | strategy_native_cohort_remove_v1 (pf_strategy_t s, uint64_t cohort, uint64_t incarnation) |
| Remove a request from a cohort roster. | |
| int | strategy_configure_native_ext_v1 (pf_strategy_t s, const pf_native_run_spec_v1 *base, const pf_native_run_spec_ext_v1 *ext) |
| Configure a native run from the v1 specification plus the extension. | |
| int | strategy_configure_native_ext_result_v1 (pf_strategy_t s, const pf_native_run_spec_v1 *base, const pf_native_run_spec_ext_v1 *ext, uint32_t *error, uint32_t *field) |
The typed spelling of strategy_configure_native_ext_v1: the same inputs, plus error / field, which receive the kernel's pf_native_spec_error_t / pf_native_spec_field_t pair once the call's phase or its specification has been judged. | |
| int | strategy_native_append_auxiliary_bars_v1 (pf_strategy_t s, const pf_bar_t *bars, int32_t n) |
Append later bars to the run's declared auxiliary feed on a realtime stream (NativeStrategyHost::append_auxiliary_bars). | |
| int | strategy_native_append_auxiliary_bars_ext_v1 (pf_strategy_t s, const pf_bar_t *bars, int32_t n, uint32_t *error, int32_t *index) |
The same append, answered by name — append_auxiliary_bars_result(). | |
| int | strategy_native_declare_opened_lot_entry_bar_mask_v1 (pf_strategy_t s, uint64_t entry_incarnation, const pf_bar_t *entry_bar, uint32_t fill_point) |
Declare where the fill that opened a lot sits on its entry bar — declare_opened_lot_entry_bar_mask(), the entry-side half of the excursion capability pf_native_callbacks_v1::on_lot_excursion owns (RULING A48). | |
| int strategy_native_api_version | ( | void | ) |
| pf_strategy_t strategy_native_host_create_v1 | ( | const pf_native_callbacks_v1 * | callbacks | ) |
Allocate a native host that forwards every kernel callback to callbacks.
The table is copied; the caller's struct need not outlive the call. The returned handle is a pf_strategy_t the existing runtime symbols accept: strategy_configure_native_v1, the whole strategy_stream_* family and the read-only accessors all take it unchanged.
reserved1 in the current layout, or an allocation failure. Release it with strategy_native_host_free — never strategy_free, which does not own this allocation. References PF_API.
Referenced by grid_without_a_ladder_is_refused(), main(), and run_mode().
| void strategy_native_host_free | ( | pf_strategy_t | s | ) |
Release a handle from strategy_native_host_create_v1.
NULL is a no-op; a handle this API did not create is refused without freeing anything.
References PF_API.
Referenced by grid_without_a_ladder_is_refused(), main(), and run_mode().
| int strategy_native_run_v1 | ( | pf_strategy_t | s, |
| const pf_bar_t * | bars, | ||
| int | n, | ||
| pf_report_t * | out ) |
Run n bars as one batch and fill out.
The specification must already be Ready (strategy_configure_native_v1). out may be NULL to skip reporting; otherwise its arrays are heap-allocated and released by strategy_native_report_free_v1.
A report belongs to THIS attempt or is empty, and a refused attempt never answers PF_NATIVE_OK. A call the host refuses without beginning (a handle that is not Ready: Unconfigured, already Completed or Failed; a refused bar array or run option) leaves the lifecycle, the run identity and the rows the handle retains exactly as they were, answers PF_NATIVE_E_RUN_FAILED and leaves out as the empty report (every array NULL, every count 0), overwritten and never freed, so it is safe whether or not the caller initialised it and strategy_native_report_free_v1 on it is a no-op; the reason is in strategy_get_last_error, strategy_get_last_error_code and strategy_last_run_status (1). A run that began and failed also answers PF_NATIVE_E_RUN_FAILED and leaves the handle Failed. It publishes partial rows unless report_sink_failed is latched: every later read gives the empty report (every array NULL, every count 0), even when the sink failed at finish time after run success. Status, code, arguments and message stay in the run-failure latch. A Completed handle runs again after strategy_configure_native_v1 (or strategy_configure_native_ext_result_v1) succeeds. Pre-engine PF_NATIVE_E_HANDLE and PF_NATIVE_E_ARGUMENT refusals leave out untouched. Every run entrypoint uses the engine's report reader: a batch refused over a live stream reads empty, and strategy_stream_fill_report keeps the stream's rows, subject to the same sink-failure gate.
References PF_API.
Referenced by main(), and run_mode().
| void strategy_native_report_free_v1 | ( | pf_report_t * | report | ) |
Free the heap arrays inside a report filled by strategy_native_run_v1.
The unprefixed report_free is a per-strategy export the transpiler emits, so it is absent from a runtime a C host links on its own: this is that host's release path. Idempotent; NULL is a no-op. The pf_report_t struct itself stays caller-owned.
References PF_API.
Referenced by main(), and run_mode().
| int strategy_native_submit_v1 | ( | pf_strategy_t | s, |
| const pf_native_request_v1 * | request, | ||
| uint64_t * | incarnation, | ||
| uint32_t * | reject ) |
Submit request.
Legal from inside a native callback; the request joins the working book and is matched by the consumer from the next execution point on. The handle it answers with is the request's identity for the rest of the run: replace, cancel and every event carry it.
| s | The host this run is driving, from strategy_create. |
| request | Borrowed for the call only; the kernel copies what it keeps. |
| incarnation | Optional; receives the accepted request's handle. |
| reject | Optional; receives a pf_native_reject_reason_t on rejection. |
Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_replace_v1 | ( | pf_strategy_t | s, |
| uint64_t | incarnation, | ||
| const pf_native_request_v1 * | request, | ||
| uint64_t * | successor ) |
Replace the live request incarnation with request.
Amendment, not cancel-and-resubmit: the predecessor leaves the book and the successor takes its place in one step, and the REPLACED event names both. A target that is no longer working is PF_NATIVE_E_NOT_WORKING.
| s | The host this run is driving, from strategy_create. |
| incarnation | The live request to amend, as strategy_native_submit_v1 handed it back. |
| request | Borrowed for the call only. |
| successor | Optional; receives the successor's handle. |
PF_NATIVE_E_REJECTED is where this signature stops: it has nowhere to put the RequestRejectReason that strategy_native_submit_v1 writes to its reject, so use strategy_native_replace_ext_v1 when the reason matters.
Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_replace_ext_v1 | ( | pf_strategy_t | s, |
| uint64_t | incarnation, | ||
| const pf_native_request_v1 * | request, | ||
| uint64_t * | successor, | ||
| uint32_t * | reject ) |
Replace the live request incarnation, reporting a rejection's reason.
The same call as strategy_native_replace_v1 — same legality, same amendment, same verdicts, same successor — with the reject out-parameter strategy_native_submit_v1 has always had. That asymmetry was the whole gap: a C++ replace answers ReplaceResult::reason and the C submit writes it out, while the C replace dropped it, so a C host learned "rejected" and no more. (strategy_native_cancel_v1 needs no such spelling: its status IS its reason.)
It is an additional symbol rather than a wider signature because this header's STABILITY rule is that a signature never changes within a major version — the same reason strategy_configure_native_ext_v1 exists beside strategy_configure_native_v1. Use either; strategy_native_replace_v1 stays exactly what it was and is this call with reject NULL.
| s | The host this run is driving, from strategy_create. |
| incarnation | The live request to amend. |
| request | Borrowed for the call only. |
| successor | Optional; receives the successor's handle. Untouched unless the replace is accepted. |
| reject | Optional; receives a pf_native_reject_reason_t, and only on PF_NATIVE_E_REJECTED. Untouched otherwise — including for NOT_WORKING and INVALID_TARGET, which are the target's verdict and not the request's. |
Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_cancel_v1 | ( | pf_strategy_t | s, |
| uint64_t | incarnation ) |
Cancel one live request.
References PF_API.
| int strategy_native_cancel_all_v1 | ( | pf_strategy_t | s | ) |
Cancel every live request, dependants included.
References PF_API.
| int strategy_native_cancel_where_v1 | ( | pf_strategy_t | s, |
| const char * | text, | ||
| uint32_t | field ) |
Cancel exactly the live requests whose field equals text.
The C spelling of NativeStrategyHost::cancel_where. With PF_NATIVE_FIELD_LABEL it is the one call that withdraws every live request a host issued under one of its own order ids; with PF_NATIVE_FIELD_COMMENT it is the established comment predicate. A dependant of a cancelled owner still leaves the book, but it is counted only when its own field matched. Text that matches nothing is not a command.
| s | The host this run is driving, from strategy_create. |
| text | Borrowed for the call only; "" matches the requests that carry no such text. NULL is PF_NATIVE_E_ARGUMENT, not "". |
| field | pf_native_request_field_t. |
text, or another negative status.Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_execute_current_v1 | ( | pf_strategy_t | s, |
| uint64_t | incarnation, | ||
| uint32_t | price_rule, | ||
| uint32_t * | refusal ) |
Execute one live request at the current execution point.
Legal only inside a callback the kernel has opened an execution point for (on_bar, on_bar_open, on_tick, on_applied, on_recalculate); anywhere else the answer is PF_NATIVE_E_STATE. The request is filled at this cursor rather than waiting for the consumer's own matching pass.
| s | The host this run is driving, from strategy_create. |
| incarnation | The live request to execute, as strategy_native_submit_v1 handed it back. A handle that is not in the working book is PF_NATIVE_E_INVALID_TARGET. |
| price_rule | pf_native_price_rule_t. |
| refusal | Optional; receives a pf_native_refusal_t when the return is PF_NATIVE_E_REFUSED. |
Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_position_v1 | ( | pf_strategy_t | s, |
| double * | signed_units, | ||
| double * | average_price, | ||
| uint64_t * | lots ) |
| int strategy_native_working_len_v1 | ( | pf_strategy_t | s | ) |
Snapshot the live working book and return its length.
The snapshot is retained on the handle: strategy_native_working_get_v1 reads from it, so a row already copied out is not invalidated by a later command. The next call to this function replaces the snapshot.
References PF_API.
| int strategy_native_working_get_v1 | ( | pf_strategy_t | s, |
| int | index, | ||
| pf_native_working_v1 * | out ) |
Copy row index of the most recent working snapshot into out.
out is an in/out size prefix: set out->struct_size to sizeof(pf_native_working_v1) before the call. Everything else is filled. A caller built against an earlier layout sends PF_NATIVE_WORKING_V1_BASE_SIZE or PF_NATIVE_WORKING_V1_ARM_SIZE and is filled exactly that far.
References PF_API.
| int strategy_native_open_lot_count_v1 | ( | pf_strategy_t | s, |
| double | mark ) |
Snapshot the open lots marked at mark and return their count.
The C spelling of NativeStrategyHost::native_open_lots(mark) (R5 gap lane N18). The snapshot is retained on the handle: strategy_native_open_lot_get_v1 reads from it, so a row already copied out is not invalidated by a later command; the next call to this function replaces it. Observation only — it moves no fill, no hash and no row — and legal wherever strategy_native_position_v1 is. A NaN mark keeps every booking fact and leaves unrealized_pnl NaN.
References PF_API.
| int strategy_native_open_lot_get_v1 | ( | pf_strategy_t | s, |
| int | index, | ||
| pf_native_open_lot_v1 * | out ) |
Copy row index of the most recent open-lot snapshot into out.
out is an in/out size prefix: set out->struct_size to sizeof(pf_native_open_lot_v1) before the call. Everything else is filled.
References PF_API.
| int strategy_native_events_v1 | ( | pf_strategy_t | s, |
| uint64_t | after_ordinal, | ||
| pf_native_event_v1 * | out, | ||
| int | cap ) |
Copy up to cap events with an ordinal strictly greater than after_ordinal into out, in the kernel's own recording order.
Ordinals are non-decreasing rather than strictly increasing: an applied execution and the account observation it produced carry the same one. A page therefore never ends in the middle of such a group (for cap >= 2), so a poller advances by the last returned ordinal without losing or repeating a row. The rows are what the run's event retention keeps (pf_native_event_retention_t): under FULL and COMMANDS the history is append-only, so the same after_ordinal always yields the same rows; under WINDOW a read answers what the window still holds, and one from below its start (strategy_native_event_window_v1) starts there.
References PF_API.
Referenced by run_mode().
| int strategy_native_acknowledge_events_v1 | ( | pf_strategy_t | s, |
| uint64_t | through_ordinal ) |
The host has read every event through through_ordinal — native_acknowledge_events().
Under the Window event retention the kernel drops the acknowledged command events at the next script-bar boundary and keeps every event above the acknowledgement; the first call also marks the host as one that polls, so a polling host calls it from on_run_begin (0 is legal). A later, smaller acknowledgement never lowers an earlier one, one above the event high water acknowledges the high water, and outside a running run the call records nothing. The Full and Commands retentions keep the whole journal whatever is acknowledged.
References PF_API.
| int strategy_native_event_window_v1 | ( | pf_strategy_t | s, |
| uint64_t * | out_first_ordinal ) |
The oldest ordinal a read can still return — native_event_window_start() — written to out_first_ordinal: every command event at or above it is retained, and strategy_native_events_v1 with an after_ordinal below it starts there.
1 while nothing was dropped.
out_first_ordinal, or another negative status. References PF_API.
| int strategy_native_state_v1 | ( | pf_strategy_t | s, |
| pf_native_state_v1 * | out ) |
Read the run's lifecycle and typed failure into out.
out is an in/out size prefix: set out->struct_size to sizeof(pf_native_state_v1) before the call.
References PF_API.
| int strategy_native_declare_subscriptions_v1 | ( | pf_strategy_t | s, |
| const pf_native_subscription_v1 * | rows, | ||
| int | n ) |
Declare this run's higher-timeframe series from inside on_run_begin — declare_timeframe_subscriptions().
The list REPLACES the subscriptions staged by strategy_configure_native_ext_v1; the kernel registers from the staged spec after the callback returns, so the run's continuation identity folds what actually ran. n may be 0 (with rows NULL), which declares no series at all.
struct_size, PF_NATIVE_E_ARGUMENT for a NULL tf or bad authoritative bars (and for a negative n or NULL rows), PF_NATIVE_E_TAG for a lookahead / gaps word outside its enumeration; then PF_NATIVE_E_STATE anywhere but inside on_run_begin and for a list this run's input timeframe would refuse — the same validation strategy_configure_native_ext_v1 applies. A refusal stages nothing. strategy_native_declare_subscriptions_ext_v1 also names which validation refused the list. References PF_API.
| int strategy_native_declare_subscriptions_ext_v1 | ( | pf_strategy_t | s, |
| const pf_native_subscription_v1 * | rows, | ||
| int | n, | ||
| const uint32_t * | sources, | ||
| uint32_t * | error, | ||
| uint32_t * | field ) |
The same declaration, answered by name — declare_timeframe_subscriptions_result().
The same call as strategy_native_declare_subscriptions_v1 — same legality, same staging, same statuses — with the refusal's words written out, and with a series source per row, so a series declared here may be built from the auxiliary feed strategy_native_declare_auxiliary_feed_v1 staged. strategy_native_declare_subscriptions_v1 stays exactly what it was: this call with sources, error and field NULL.
| s | The host this run is driving. |
| rows | n rows, borrowed for the call; NULL when n is 0. |
| n | Row count (0 declares no series at all). |
| sources | Optional: n pf_native_series_source_t words, one per row. NULL builds every series from the input. |
| error | Optional; receives a pf_native_spec_error_t whenever the kernel judged the call: PF_NATIVE_SPEC_ERROR_NONE when staged, PF_NATIVE_SPEC_ERROR_WRONG_PHASE outside on_run_begin, else the first error the list's validation found — the validation strategy_configure_native_ext_v1 applies. |
| field | Optional; receives the pf_native_spec_field_t beside it. |
error, in which case nothing is staged; PF_NATIVE_E_ARGUMENT / E_STRUCT / E_TAG for a row the C layer refuses before the kernel sees the list, leaving error and field untouched.Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_declare_auxiliary_feed_v1 | ( | pf_strategy_t | s, |
| const char * | tf, | ||
| const pf_bar_t * | bars, | ||
| int32_t | n, | ||
| uint32_t * | error, | ||
| uint32_t * | field ) |
Declare, replace or withdraw this run's auxiliary finer feed from inside on_run_begin — declare_auxiliary_feed_result().
The feed REPLACES the one staged by strategy_configure_native_ext_v1's auxiliary tail, and the kernel registers from the staged spec after the callback returns. It is judged together with the series staged at that moment, so a host that declares both here declares the feed first and its feed-built series second (strategy_native_declare_subscriptions_ext_v1).
| s | The host this run is driving. |
| tf | The feed's timeframe literal, or NULL to withdraw the staged feed (with n 0 and bars NULL). |
| bars | n strictly increasing bars, copied; NULL when n is 0. |
| n | Bar count. |
| error | Optional; receives a pf_native_spec_error_t whenever the kernel judged the call (PF_NATIVE_SPEC_ERROR_NONE when staged, PF_NATIVE_SPEC_ERROR_WRONG_PHASE outside on_run_begin). |
| field | Optional; receives the pf_native_spec_field_t beside it. |
error — a feed the input timeframe refuses, or a withdrawal that would strand a staged feed-built series — changing nothing; PF_NATIVE_E_ARGUMENT for a negative n, NULL bars with n > 0, or a withdrawal carrying bars, leaving error and field untouched.Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_partial_bar_v1 | ( | pf_strategy_t | s, |
| pf_bar_t * | out ) |
The bar so far — current_partial_bar().
Open of the script bar's first modeled point, running high/low, close at the last path point the walk has consumed: the cursor itself at a discrete point (the open of the bar or of a sub-bar, a distribution sample, an observed print), and the segment's origin at a fill inside a segment, whose on_applied and ORDER_FILL recalculation read the bar before the fill price is folded in. Volume is the activity actually consumed so far. Valid in the bar-open, applied, tick, sub-bar and recalculation callbacks.
out was written, PF_NATIVE_ABSENT outside a path walk — including in the bar's own close calculation, where the callback already holds the complete bar — leaving out untouched. References PF_API.
| int strategy_native_recalculations_v1 | ( | pf_strategy_t | s, |
| uint64_t * | driven, | ||
| uint64_t * | skipped ) |
How many recalculations the kernel drove, and how many it suppressed because a point had spent its max_recalculations_per_point budget — native_recalculation_count() / native_recalculations_skipped().
Either pointer may be NULL. Observation only.
References PF_API.
| int strategy_native_trail_state_v1 | ( | pf_strategy_t | s, |
| uint64_t | incarnation, | ||
| pf_native_trail_state_v1 * | out ) |
The trail projection of one live request — trail_state().
incarnation names a request this run issued.
out was written, PF_NATIVE_ABSENT when the handle is not a live Trail request (unknown, finished, or another trigger), leaving out untouched. References PF_API.
| int strategy_native_series_bar_v1 | ( | pf_strategy_t | s, |
| uint32_t | subscription, | ||
| pf_bar_t * | out ) |
The latest completed bucket of a declared subscription — native_series_bar().
subscription is the row's index in the subscriptions array strategy_configure_native_ext_v1 was given (or the list strategy_native_declare_subscriptions_v1 installed). Legal inside every callback, on_timeframe_bar included.
out was written, PF_NATIVE_ABSENT before the series' first delivery, for an unknown index, and on every input bar a PF_NATIVE_GAPS_CLEAR series publishes nothing on — the empty that stands for na. References PF_API.
| int strategy_native_timeframe_bar_interval_v1 | ( | pf_strategy_t | s, |
| pf_native_timeframe_interval_v1 * | out ) |
Read the delivered bucket's own calendar interval from inside pf_native_callbacks_v1::on_timeframe_bar.
The returned fields are exactly the C++ NativeTimeframeBarContext::interval; no interval is inferred from the delivered bar or its delivery timestamp. out is size-prefixed.
References PF_API.
| int strategy_native_marked_equity_v1 | ( | pf_strategy_t | s, |
| double | mark, | ||
| double * | out ) |
The account's marked equity at mark — native_marked_equity().
References PF_API.
| int strategy_native_liquidation_price_v1 | ( | pf_strategy_t | s, |
| double * | out ) |
The price at which the marked equity falls below the run's maintenance requirement for the live position's side — native_liquidation_price().
out was written, PF_NATIVE_ABSENT when the run declares no margin model, the side has no maintenance fraction, the book is flat, or no finite price solves the breach (a long at full maintenance); out is then written NaN. References PF_API.
| int strategy_native_sized_units_v1 | ( | pf_strategy_t | s, |
| const pf_native_request_v1 * | sized, | ||
| double | price, | ||
| double | equity, | ||
| double | fx, | ||
| double * | units ) |
The units a kernel-sized request resolves to under this run's spec, as a pure query — native_sized_units().
sized is a PF_NATIVE_INTENT_SIZED request, read for its sizing block alone (side, basis and its value, reserve, grid policy): units = cash / (price * point_value * fx), the cash being the basis value or the fraction of equity, net of the percent fee reserve when the request asks for it, then the grid policy. It is the very function the kernel sizes with, at acceptance and at the candidate, so a host that gates a command on its quantity reads the number here before it submits. Observation only: it moves and freezes nothing.
| s | The host whose run spec sizes the request. |
| sized | The PF_NATIVE_INTENT_SIZED request to size, borrowed for the call. |
| price | The sizing price. |
| equity | The marked equity an EQUITY_FRACTION basis is a share of. |
| fx | The account rate the conversion divides by. |
| units | Receives the units; NaN with PF_NATIVE_ABSENT. |
Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_risk_state_v1 | ( | pf_strategy_t | s, |
| pf_native_risk_state_v1 * | out ) |
The run's generic risk ledger — native_risk_state().
Every field is its zero for a run that declares no risk block.
References PF_API.
| int strategy_native_margin_call_v1 | ( | pf_strategy_t | s, |
| uint64_t | ordinal, | ||
| pf_native_margin_call_v1 * | out ) |
The whole economics of one margin call — what a C++ host's on_native_margin_call receives as MarginCallEvent.
ordinal is the call's event ordinal: the ordinal of the pf_native_event_v1 pf_native_callbacks_v1::on_margin_call is handed, or of a PF_NATIVE_EVENT_MARGIN_CALL row strategy_native_events_v1 returns. Legal inside on_margin_call and anywhere the event history is; observation only.
out is an in/out size prefix: set out->struct_size to sizeof(pf_native_margin_call_v1) before the call.
out was written, PF_NATIVE_ABSENT when no margin call of this run has that ordinal (out untouched), PF_NATIVE_E_STRUCT for a mis-sized row, or another negative status.Exercised by the fx-roll scenario of tests/test_native_c_api.c.
References PF_API.
| int strategy_native_continuation_hash_v1 | ( | pf_strategy_t | s, |
| uint64_t * | out ) |
The run's continuation identity — native_continuation_hash().
Two runs driven the same way that folded the same declarations and the same inputs answer the same value; a batch and a stream over identical bars booking identical trades do NOT, because the driving mode is part of a continuation. It is the C spelling of the hash a stream resumes against, and the same reason the per-bar broker-state hash is per driving mode (pineforge.h, strategy_set_broker_state_hash_recording).
References PF_API.
| int strategy_native_cohort_open_v1 | ( | pf_strategy_t | s, |
| uint64_t * | cohort ) |
Open a cohort roster for PF_NATIVE_OWNER_BIND_COHORT.
References PF_API.
| int strategy_native_cohort_add_v1 | ( | pf_strategy_t | s, |
| uint64_t | cohort, | ||
| uint64_t | incarnation ) |
Enrol a live request into a cohort roster.
References PF_API.
| int strategy_native_cohort_remove_v1 | ( | pf_strategy_t | s, |
| uint64_t | cohort, | ||
| uint64_t | incarnation ) |
Remove a request from a cohort roster.
References PF_API.
| int strategy_configure_native_ext_v1 | ( | pf_strategy_t | s, |
| const pf_native_run_spec_v1 * | base, | ||
| const pf_native_run_spec_ext_v1 * | ext ) |
Configure a native run from the v1 specification plus the extension.
Use this INSTEAD of strategy_configure_native_v1, not after it: the kernel configures a host exactly once and refuses (and fails) a second attempt, so this call takes both halves and applies them together. base is the same pf_native_run_spec_v1 the other entry point takes.
Refuses without mutation — the handle stays usable — for an already-configured handle, a mis-sized struct, an unknown enumerator, or a specification the kernel's own validation rejects, which answers PF_NATIVE_E_ARGUMENT: the call validates the whole specification before it configures, so a rejected one leaves the handle Unconfigured.
References PF_API.
Referenced by grid_without_a_ladder_is_refused(), and run_mode().
| int strategy_configure_native_ext_result_v1 | ( | pf_strategy_t | s, |
| const pf_native_run_spec_v1 * | base, | ||
| const pf_native_run_spec_ext_v1 * | ext, | ||
| uint32_t * | error, | ||
| uint32_t * | field ) |
The typed spelling of strategy_configure_native_ext_v1: the same inputs, plus error / field, which receive the kernel's pf_native_spec_error_t / pf_native_spec_field_t pair once the call's phase or its specification has been judged.
Whether either out-parameter is non-NULL decides which handles it accepts:
on_hash_extension during a hash read of a Completed host.On an accepted handle the specification is validated before the kernel sees it: a refused value answers PF_NATIVE_E_ARGUMENT with its pair and leaves the handle as it was. A reuse whose session key is not the one the handle's runs are bound to, or whose run number does not exceed the highest one the handle has run, answers PF_NATIVE_E_ARGUMENT with PF_NATIVE_SPEC_ERROR_SESSION_KEY_CHANGED_ON_REUSE / PF_NATIVE_SPEC_FIELD_SESSION_KEY or PF_NATIVE_SPEC_ERROR_RUN_NUMBER_NOT_ABOVE_CONSUMED_HIGH_WATER / PF_NATIVE_SPEC_FIELD_RUN_NUMBER. That refusal latches a Completed handle Failed with PF_NATIVE_FAILURE_CONTRACT, which no configure call accepts again; an aborted handle keeps its abort and may be configured again. PF_NATIVE_OK writes NONE / NONE and leaves the handle Ready.
C-layer shape refusals leave both out-parameters untouched: a NULL handle (PF_NATIVE_E_HANDLE); NULL base, ext, or required string member; a negative auxiliary count or a NULL subscription timeframe (PF_NATIVE_E_ARGUMENT); a mis-sized struct (PF_NATIVE_E_STRUCT); or an unknown enumerator on an accepted handle (PF_NATIVE_E_TAG).
Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_append_auxiliary_bars_v1 | ( | pf_strategy_t | s, |
| const pf_bar_t * | bars, | ||
| int32_t | n ) |
Append later bars to the run's declared auxiliary feed on a realtime stream (NativeStrategyHost::append_auxiliary_bars).
Legal between stream inputs, after strategy_stream_begin, on a host whose specification declared PF_NATIVE_SPEC_EXT_AUXILIARY_FEED. The bars are copied, join the feed behind every bar it holds, and ride on the next pushed bar whose period they opened before — the routing a batch of the same bars applies. n of 0 is accepted and appends nothing.
Refused without mutation, the handle staying usable, for bars that are out of order or not after the feed's last bar, a bar with invalid OHLCV, a bar that opened inside an input period already accepted, a host that declared no feed, and a run that is not realtime: PF_NATIVE_E_STATE, the reason readable with strategy_get_last_error and, by name, from strategy_native_append_auxiliary_bars_ext_v1. A call from inside a callback fails the run, as every reentrant stream input does.
References PF_API.
| int strategy_native_append_auxiliary_bars_ext_v1 | ( | pf_strategy_t | s, |
| const pf_bar_t * | bars, | ||
| int32_t | n, | ||
| uint32_t * | error, | ||
| int32_t * | index ) |
The same append, answered by name — append_auxiliary_bars_result().
The same call as strategy_native_append_auxiliary_bars_v1 — same legality, same appended bars, same statuses, the same latched contract failure for a call from inside a callback — with the refusal written out. strategy_native_append_auxiliary_bars_v1 stays this call with both out-parameters NULL.
| s | The host this run is driving. |
| bars | n bars, strictly increasing and after the feed's last bar, copied; NULL when n is 0. |
| n | Bar count; 0 appends nothing. |
| error | Optional; receives a pf_native_append_error_t whenever the kernel judged the call (PF_NATIVE_APPEND_ERROR_NONE when appended). |
| index | Optional; receives the bar OF THIS CALL the refusal stopped on, 0 for a refusal that is not about one bar and for an applied append. |
error, or PF_NATIVE_E_ARGUMENT for a negative n or NULL bars with n > 0, which the C layer refuses itself, leaving both out-parameters untouched.Exercised by tests/test_native_c_api.c.
References PF_API.
| int strategy_native_declare_opened_lot_entry_bar_mask_v1 | ( | pf_strategy_t | s, |
| uint64_t | entry_incarnation, | ||
| const pf_bar_t * | entry_bar, | ||
| uint32_t | fill_point ) |
Declare where the fill that opened a lot sits on its entry bar — declare_opened_lot_entry_bar_mask(), the entry-side half of the excursion capability pf_native_callbacks_v1::on_lot_excursion owns (RULING A48).
The host says only WHERE its fill sat. The kernel walks entry_bar's modeled path in the run's own leg order, the one its matcher walks — pf_native_run_spec_ext_v1::path_order when HIGH_FIRST or LOW_FIRST, and under AUTO the high first when |high - open| < |open - low|, the low first otherwise — finds where a price is first touched on it, and sets the two entry-bar masks of every open lot booked under entry_incarnation: the ends of the bar the path had already reached before that lot's own price. They come back on the lot's closing facts, pf_native_lot_excursion_v1::entry_bar_high_masked and entry_bar_low_masked. A fill the path never reaches leaves the lot as it was, and so does an incarnation that booked no open lot. The masks are durable lot state, folded into the broker-state hash.
Legal inside on_applied alone — the frame in which a host learns that a fill opened a lot (pf_native_applied_v1::opened_lot_incarnation) — and refused with PF_NATIVE_E_STATE everywhere else, changing nothing.
| s | The host this run is driving, from strategy_create. |
| entry_incarnation | The request whose fill opened the lot. |
| entry_bar | The whole bar the fill sat on; borrowed. |
| fill_point | pf_native_opened_lot_fill_point_t. |
entry_bar, PF_NATIVE_E_TAG for a fill point outside the enumeration, PF_NATIVE_E_STATE outside on_applied, or another negative status. References PF_API.