Entry points

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_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_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_partial_bar_v1 (pf_strategy_t s, pf_bar_t *out)
	The bar so far at the current cursor — 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_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_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_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_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).

Detailed Description

Function Documentation

strategy_native_api_version()

int strategy_native_api_version

(

void

)

This header's layout version.

Mirrors strategy_stream_api_version.

References PF_API.

strategy_native_host_create_v1()

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, the read-only accessors and report_free all take it unchanged.

Returns

The handle, or NULL for a NULL/mis-sized table or on 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().

strategy_native_host_free()

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().

strategy_native_run_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.

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 report_free.

Returns

PF_NATIVE_OK when the run reached Completed, PF_NATIVE_E_RUN_FAILED when it did not (read strategy_native_state_v1 for the code).

References PF_API.

Referenced by main(), and run_mode().

strategy_native_report_free_v1()

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().

strategy_native_submit_v1()

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.

Parameters

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 RequestRejectReason on rejection.

Returns

PF_NATIVE_OK when accepted, PF_NATIVE_E_REJECTED when the kernel rejected it, PF_NATIVE_E_STATE when commands are not legal here.

Exercised by tests/test_native_c_api.c.

References PF_API.

Referenced by on_bar(), and submit().

strategy_native_replace_v1()

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.

Parameters

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.

Returns

PF_NATIVE_OK, PF_NATIVE_E_REJECTED, PF_NATIVE_E_NOT_WORKING, PF_NATIVE_E_INVALID_TARGET, or PF_NATIVE_E_STATE.

Exercised by tests/test_native_c_api.c.

References PF_API.

strategy_native_cancel_v1()

int strategy_native_cancel_v1	(	pf_strategy_t	s,
		uint64_t	incarnation )

Cancel one live request.

Returns

PF_NATIVE_OK, PF_NATIVE_E_NOT_WORKING, PF_NATIVE_E_INVALID_TARGET or PF_NATIVE_E_STATE.

References PF_API.

strategy_native_cancel_all_v1()

int strategy_native_cancel_all_v1

(

pf_strategy_t

s

)

Cancel every live request, dependants included.

Returns

The number cancelled (>= 0), or PF_NATIVE_E_STATE.

References PF_API.

strategy_native_cancel_where_v1()

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.

Parameters

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.

Returns

The number cancelled (>= 0), PF_NATIVE_E_TAG for a field outside the enumeration, PF_NATIVE_E_ARGUMENT for a NULL text, or another negative status.

Exercised by tests/test_native_c_api.c.

References PF_API.

strategy_native_execute_current_v1()

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.

Parameters

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.

Returns

A non-negative pf_native_execute_outcome_t, or a negative status.

Exercised by tests/test_native_c_api.c.

References PF_API.

strategy_native_position_v1()

int strategy_native_position_v1	(	pf_strategy_t	s,
		double *	signed_units,
		double *	average_price,
		uint64_t *	lots )

Read the physical position.

Every output is optional.

Returns

PF_NATIVE_OK, or a negative status.

References PF_API.

Referenced by on_bar().

strategy_native_working_len_v1()

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.

Returns

The row count (>= 0), or a negative status.

References PF_API.

strategy_native_working_get_v1()

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.

Returns

PF_NATIVE_OK, PF_NATIVE_E_ARGUMENT for an out-of-range index, PF_NATIVE_E_STRUCT for a mis-sized row, or another negative status.

References PF_API.

strategy_native_open_lot_count_v1()

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.

Returns

The row count (>= 0), or a negative status.

References PF_API.

strategy_native_open_lot_get_v1()

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.

Returns

PF_NATIVE_OK, PF_NATIVE_E_ARGUMENT for an out-of-range index, PF_NATIVE_E_STRUCT for a mis-sized row, or another negative status.

References PF_API.

strategy_native_events_v1()

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 history is append-only, so the same after_ordinal always yields the same rows.

Returns

The number written (>= 0), or a negative status.

References PF_API.

Referenced by run_mode().

strategy_native_state_v1()

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.

strategy_native_declare_subscriptions_v1()

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.

Returns

PF_NATIVE_OK when the list was staged; 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 — in which case nothing is staged and nothing changes.

References PF_API.

strategy_native_partial_bar_v1()

int strategy_native_partial_bar_v1	(	pf_strategy_t	s,
		pf_bar_t *	out )

The bar so far at the current cursor — current_partial_bar().

Open of the script bar's first modeled point, running high/low, close at the cursor; volume is the activity actually consumed so far. Valid in the bar-open, applied, tick, sub-bar and recalculation callbacks.

Returns

PF_NATIVE_OK when 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.

strategy_native_recalculations_v1()

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.

strategy_native_trail_state_v1()

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.

Returns

PF_NATIVE_OK when 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.

strategy_native_series_bar_v1()

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.

Returns

PF_NATIVE_OK when out was written, PF_NATIVE_ABSENT before the series' first delivery, for an unknown index, and on every input bar a gaps = 1 series publishes nothing on — the empty that stands for na.

References PF_API.

strategy_native_marked_equity_v1()

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.

strategy_native_liquidation_price_v1()

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().

Returns

PF_NATIVE_OK when 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.

strategy_native_risk_state_v1()

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.

strategy_native_continuation_hash_v1()

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.

strategy_native_cohort_open_v1()

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.

strategy_native_cohort_add_v1()

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.

strategy_native_cohort_remove_v1()

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.

strategy_configure_native_ext_v1()

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.

Returns

PF_NATIVE_OK, or a negative status.

References PF_API.

Referenced by grid_without_a_ladder_is_refused(), and run_mode().

strategy_native_append_auxiliary_bars_v1()

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. A call from inside a callback fails the run, as every reentrant stream input does.

Returns

PF_NATIVE_OK, or a negative status.

References PF_API.