RAII wrapper around one compiled PineForge strategy plugin. More...

#include <pineforge/hpo/strategy_plugin.hpp>

Public Member Functions
	StrategyPlugin (std::filesystem::path path)
	Loads `path` and resolves the required PineForge strategy symbols.

	~StrategyPlugin ()

	StrategyPlugin (const StrategyPlugin &)=delete

StrategyPlugin &	operator= (const StrategyPlugin &)=delete

	StrategyPlugin (StrategyPlugin &&other) noexcept

StrategyPlugin &	operator= (StrategyPlugin &&other) noexcept

const std::filesystem::path &	path () const noexcept
	Returns the dynamic-library path supplied at construction.

int	abi_version () const noexcept
	Returns the ABI version reported by the validated plugin.

pf_strategy_t	create_strategy () const
	Creates a fresh strategy handle owned by the caller.

void	free_strategy (pf_strategy_t strategy) const noexcept
	Releases a handle returned by create_strategy(); safe to call during cleanup.

void	set_input (pf_strategy_t strategy, const std::string &key, const std::string &value) const
	Applies one serialized Pine input before the backtest starts.

void	set_override (pf_strategy_t strategy, const std::string &key, const std::string &value) const
	Applies one serialized runtime strategy override before the backtest starts.

void	set_chart_timezone (pf_strategy_t strategy, const std::string &timezone) const
	Sets the chart timezone when non-empty and supported by the plugin.

void	set_symbol_info (pf_strategy_t strategy, const SymbolInfo &info) const
	Applies the lot grid (metadata keys `qty_step`, then `mincontract`) first, then the metadata key `series_origin_ms`, mintick, pointvalue, exchange timezone, and session.

void	set_symbol_feeds (pf_strategy_t strategy, const SymbolFeeds &symbols) const
	Installs fixed other-symbol facts and bars into a fresh strategy handle.

void	set_scratch_tables_bounded_default (pf_strategy_t strategy) const
	Installs backend 1 with all-zero maxima; the engine expands its default tier at begin.

void	require_scratch_arena (pf_strategy_t strategy) const
	Admits the inherited arena using the engine's environment and backing checks.

void	run_backtest_full (pf_strategy_t strategy, const pf_bar_t bars, int bar_count, const std::string &input_timeframe, const std::string &script_timeframe, bool bar_magnifier, int magnifier_samples, pf_magnifier_distribution_t magnifier_distribution, pf_report_t report) const
	Invokes the plugin's full backtest entry point using immutable OHLCV input.

std::string	last_error (pf_strategy_t strategy) const
	Returns the plugin's last error for `strategy`, or an empty string when none exists.

std::optional< std::string >	last_error_code (pf_strategy_t strategy) const
	Returns an engine code, or nullopt when the optional getter is unavailable.

std::optional< std::string >	last_error_args (pf_strategy_t strategy) const
	Returns raw engine argument JSON, or nullopt when its getter is unavailable.

std::optional< std::int32_t >	last_run_status (pf_strategy_t strategy) const
	Returns the optional run status; status 1 denotes a failed execution.

bool	selected_window_available () const noexcept
	Returns whether all six selected-window/observer exports exist; does not admit a revision.

void	require_selected_window (const std::optional< std::string > &expected_manifest_version=std::nullopt) const
	Requires all six exports in protocol order, ABI versions 1, then an admitted engine.

EngineVersion	engine_version (const std::optional< std::string > &expected_manifest_version=std::nullopt) const
	Reads and validates this plugin's embedded runtime identity, optionally against a manifest.

void	set_selected_window (pf_strategy_t strategy, std::int64_t start_ms, std::int64_t end_ms) const
	Configures the next selected run's half-open interval using the engine's v1 descriptor.

void	clear_selected_window (pf_strategy_t strategy) const
	Clears pending selection; subject to the same checked status rules as its setter.

pf_selected_window_counts_v1	selected_window_counts (pf_strategy_t strategy) const
	Reads native counts with initialized and checked engine headers.

void	set_execution_observer (pf_strategy_t strategy, const pf_execution_observer_v1 *observer) const
	Registers an observer, or removes it when `observer` is null.

pf_execution_observation_v1	execution_observation (pf_strategy_t strategy) const
	Reads the execution snapshot; a refusal or changed header is `hpo_invariant`.

std::optional< std::string >	effective_settings (pf_strategy_t strategy) const
	Returns optional version-1 effective-settings JSON using the bounded two-call protocol.

void	free_report (pf_report_t *report) const noexcept
	Releases report-owned allocations populated by run_backtest_full().

Detailed Description

RAII wrapper around one compiled PineForge strategy plugin.

The dynamic library is loaded and ABI-validated once. It may serve concurrent calls made with distinct strategy handles, but each pf_strategy_t must remain confined to one trial. Reports and strategy handles must be released through this wrapper before the plugin is destroyed.

Definition at line 66 of file strategy_plugin.hpp.

Constructor & Destructor Documentation

◆ StrategyPlugin() [1/3]

pineforge::hpo::StrategyPlugin::StrategyPlugin ( std::filesystem::path path )

explicit

Loads path and resolves the required PineForge strategy symbols.

Exceptions

std::invalid_argument	when the path is empty.
std::runtime_error	when loading, symbol resolution, or ABI validation fails.

◆ ~StrategyPlugin()

pineforge::hpo::StrategyPlugin::~StrategyPlugin ( )

◆ StrategyPlugin() [2/3]

pineforge::hpo::StrategyPlugin::StrategyPlugin ( const StrategyPlugin & )

delete

◆ StrategyPlugin() [3/3]

pineforge::hpo::StrategyPlugin::StrategyPlugin ( StrategyPlugin && other )

noexcept

Member Function Documentation

◆ abi_version()

int pineforge::hpo::StrategyPlugin::abi_version ( ) const

inlinenoexcept

Returns the ABI version reported by the validated plugin.

Definition at line 82 of file strategy_plugin.hpp.

◆ clear_selected_window()

void pineforge::hpo::StrategyPlugin::clear_selected_window ( pf_strategy_t strategy ) const

Clears pending selection; subject to the same checked status rules as its setter.

Callers outside SelectedEvaluation::evaluate must call require_selected_window() first; this method does not enforce admission when its own symbol exists.

◆ create_strategy()

pf_strategy_t pineforge::hpo::StrategyPlugin::create_strategy ( ) const

Creates a fresh strategy handle owned by the caller.

Prefers optional checked creation and otherwise uses the legacy factory.

Exceptions

std::runtime_error when the plugin returns a null handle.

◆ effective_settings()

std::optional< std::string > pineforge::hpo::StrategyPlugin::effective_settings ( pf_strategy_t strategy ) const

Returns optional version-1 effective-settings JSON using the bounded two-call protocol.

An absent getter or unusable receipt is nullopt, never a settings attestation.

◆ engine_version()

EngineVersion pineforge::hpo::StrategyPlugin::engine_version ( const std::optional< std::string > & expected_manifest_version = std::nullopt ) const

Reads and validates this plugin's embedded runtime identity, optionally against a manifest.

Exceptions

HpoError with code hpo_walkforward_unavailable for invalid metadata or revision.

◆ execution_observation()

pf_execution_observation_v1 pineforge::hpo::StrategyPlugin::execution_observation ( pf_strategy_t strategy ) const

Reads the execution snapshot; a refusal or changed header is hpo_invariant.

Callers outside SelectedEvaluation::evaluate must call require_selected_window() first; this method does not enforce admission when its own symbol exists.

◆ free_report()

void pineforge::hpo::StrategyPlugin::free_report ( pf_report_t * report ) const

noexcept

Releases report-owned allocations populated by run_backtest_full().

◆ free_strategy()

void pineforge::hpo::StrategyPlugin::free_strategy ( pf_strategy_t strategy ) const

noexcept

Releases a handle returned by create_strategy(); safe to call during cleanup.

◆ last_error()

std::string pineforge::hpo::StrategyPlugin::last_error ( pf_strategy_t strategy ) const

Returns the plugin's last error for strategy, or an empty string when none exists.

Exceptions

std::invalid_argument for a null handle.

◆ last_error_args()

std::optional< std::string > pineforge::hpo::StrategyPlugin::last_error_args ( pf_strategy_t strategy ) const

Returns raw engine argument JSON, or nullopt when its getter is unavailable.

◆ last_error_code()

std::optional< std::string > pineforge::hpo::StrategyPlugin::last_error_code ( pf_strategy_t strategy ) const

Returns an engine code, or nullopt when the optional getter is unavailable.

◆ last_run_status()

std::optional< std::int32_t > pineforge::hpo::StrategyPlugin::last_run_status ( pf_strategy_t strategy ) const

Returns the optional run status; status 1 denotes a failed execution.

◆ operator=() [1/2]

StrategyPlugin & pineforge::hpo::StrategyPlugin::operator= ( const StrategyPlugin & )

delete

◆ operator=() [2/2]

StrategyPlugin & pineforge::hpo::StrategyPlugin::operator= ( StrategyPlugin && other )

noexcept

◆ path()

const std::filesystem::path & pineforge::hpo::StrategyPlugin::path ( ) const

inlinenoexcept

Returns the dynamic-library path supplied at construction.

Definition at line 80 of file strategy_plugin.hpp.

◆ require_scratch_arena()

void pineforge::hpo::StrategyPlugin::require_scratch_arena ( pf_strategy_t strategy ) const

Admits the inherited arena using the engine's environment and backing checks.

The first successful attach ignores SIGXFSZ process-wide; reattachment is idempotent.

Exceptions

HpoError	with engine code `strategy_library_incompatible` if admission is absent.
EngineError	preserving the engine's code and raw argument JSON on refusal.

◆ require_selected_window()

void pineforge::hpo::StrategyPlugin::require_selected_window ( const std::optional< std::string > & expected_manifest_version = std::nullopt ) const

Requires all six exports in protocol order, ABI versions 1, then an admitted engine.

The diagnostic lists every absent protocol export; the reason names the first.

Exceptions

HpoError with code hpo_walkforward_unavailable on admission failure.

◆ run_backtest_full()

void pineforge::hpo::StrategyPlugin::run_backtest_full	(	pf_strategy_t	strategy,
		const pf_bar_t *	bars,
		int	bar_count,
		const std::string &	input_timeframe,
		const std::string &	script_timeframe,
		bool	bar_magnifier,
		int	magnifier_samples,
		pf_magnifier_distribution_t	magnifier_distribution,
		pf_report_t *	report
	)		const

Invokes the plugin's full backtest entry point using immutable OHLCV input.

The report remains caller-owned and must later be released with free_report().

Exceptions

std::invalid_argument for invalid pointers/counts or embedded-NUL timeframes.

◆ selected_window_available()

bool pineforge::hpo::StrategyPlugin::selected_window_available ( ) const

noexcept

Returns whether all six selected-window/observer exports exist; does not admit a revision.

◆ selected_window_counts()

pf_selected_window_counts_v1 pineforge::hpo::StrategyPlugin::selected_window_counts ( pf_strategy_t strategy ) const

Reads native counts with initialized and checked engine headers.

Any getter refusal, including -2 after a successful run, is hpo_invariant. Callers outside SelectedEvaluation::evaluate must call require_selected_window() first; this method does not enforce admission when its own symbol exists.

◆ set_chart_timezone()

void pineforge::hpo::StrategyPlugin::set_chart_timezone	(	pf_strategy_t	strategy,
		const std::string &	timezone
	)		const

Sets the chart timezone when non-empty and supported by the plugin.

An empty timezone is a no-op. A non-empty value requires the optional strategy_set_chart_timezone symbol.

Exceptions

std::invalid_argument	for a null handle or embedded NUL.
std::runtime_error	when the loaded plugin lacks timezone support.

◆ set_execution_observer()

void pineforge::hpo::StrategyPlugin::set_execution_observer	(	pf_strategy_t	strategy,
		const pf_execution_observer_v1 *	observer
	)		const

Registers an observer, or removes it when observer is null.

Borrowed callback/context lifetime follows the engine header, including removal refusal. Setter -2 is unavailable, -4 is engine out_of_memory; other refusals are invariants. Callers outside SelectedEvaluation::evaluate must call require_selected_window() first; this method does not enforce admission when its own symbol exists.

◆ set_input()

void pineforge::hpo::StrategyPlugin::set_input	(	pf_strategy_t	strategy,
		const std::string &	key,
		const std::string &	value
	)		const

Applies one serialized Pine input before the backtest starts.

Uses the optional checked setter when exported; refuses rejected settings.

Exceptions

std::invalid_argument	for a null handle or an embedded NUL in key/value.
std::runtime_error	for an engine-rejected setting.

◆ set_override()

void pineforge::hpo::StrategyPlugin::set_override	(	pf_strategy_t	strategy,
		const std::string &	key,
		const std::string &	value
	)		const

Applies one serialized runtime strategy override before the backtest starts.

Uses the optional checked setter when exported; refuses rejected settings.

Exceptions

std::invalid_argument	for a null handle or an embedded NUL in key/value.
std::runtime_error	for an engine-rejected setting.

◆ set_scratch_tables_bounded_default()

void pineforge::hpo::StrategyPlugin::set_scratch_tables_bounded_default ( pf_strategy_t strategy ) const

Installs backend 1 with all-zero maxima; the engine expands its default tier at begin.

Exceptions

HpoError	with engine code `strategy_library_incompatible` if the setter is absent.
EngineError	when the engine refuses the descriptor.

◆ set_selected_window()

void pineforge::hpo::StrategyPlugin::set_selected_window	(	pf_strategy_t	strategy,
		std::int64_t	start_ms,
		std::int64_t	end_ms
	)		const

Configures the next selected run's half-open interval using the engine's v1 descriptor.

Setter -2 is unavailable, -4 is engine out_of_memory; other refusals are invariants. Callers outside SelectedEvaluation::evaluate must call require_selected_window() first; this method does not enforce admission when its own symbol exists.

◆ set_symbol_feeds()

void pineforge::hpo::StrategyPlugin::set_symbol_feeds	(	pf_strategy_t	strategy,
		const SymbolFeeds &	symbols
	)		const

Installs fixed other-symbol facts and bars into a fresh strategy handle.

Exceptions

std::runtime_error naming a missing setter or refused symbol/timeframe.

◆ set_symbol_info()

void pineforge::hpo::StrategyPlugin::set_symbol_info	(	pf_strategy_t	strategy,
		const SymbolInfo &	info
	)		const

Applies the lot grid (metadata keys qty_step, then mincontract) first, then the metadata key series_origin_ms, mintick, pointvalue, exchange timezone, and session.

Exceptions

std::runtime_error	when a requested optional setter is unavailable; a declared `mincontract` or `series_origin_ms` is never silently omitted.
std::invalid_argument	for a null handle, non-positive numbers, an origin at or above 2^53, or embedded NUL.

The documentation for this class was generated from the following file:

strategy_plugin.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ StrategyPlugin() [1/3]

◆ ~StrategyPlugin()

◆ StrategyPlugin() [2/3]

◆ StrategyPlugin() [3/3]

Member Function Documentation

◆ abi_version()

◆ clear_selected_window()

◆ create_strategy()

◆ effective_settings()

◆ engine_version()

◆ execution_observation()

◆ free_report()

◆ free_strategy()

◆ last_error()

◆ last_error_args()

◆ last_error_code()

◆ last_run_status()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ path()

◆ require_scratch_arena()

◆ require_selected_window()

◆ run_backtest_full()

◆ selected_window_available()

◆ selected_window_counts()

◆ set_chart_timezone()

◆ set_execution_observer()

◆ set_input()

◆ set_override()

◆ set_scratch_tables_bounded_default()

◆ set_selected_window()

◆ set_symbol_feeds()

◆ set_symbol_info()