pineforge::hpo::WindowPlanHelper Class Reference

Owns a verified, privately snapshotted standalone planner library. More...

#include <pineforge/hpo/window_plan.hpp>

Public Member Functions
	~WindowPlanHelper ()
	Closes the library without deleting the snapshot.
	WindowPlanHelper (const WindowPlanHelper &)=delete
	A library owner cannot be copied.
WindowPlanHelper &	operator= (const WindowPlanHelper &)=delete
	A library owner cannot be copied.
	WindowPlanHelper (WindowPlanHelper &&other) noexcept
	Transfers ownership of the library and snapshot identity.
WindowPlanHelper &	operator= (WindowPlanHelper &&other) noexcept
	Closes the previous library and transfers ownership without deleting either snapshot.
PlanResult	plan_selected_primary (const pf_bar_t *rows, std::size_t count, const PlanRequest &request) const
	Calls the C bridge with exactly rows, without copying or repacking the bar array.
std::uint32_t	version () const noexcept
	Returns the validated bridge version, 1.
const std::filesystem::path &	source_path () const noexcept
	Returns the absolute source path supplied to load(), for provenance only.
std::uint64_t	source_device () const noexcept
	Returns the device of the opened, verified source, even if its pathname was replaced.
std::uint64_t	source_inode () const noexcept
	Returns the inode of the opened, verified source, even if its pathname was replaced.
std::uint64_t	source_size () const noexcept
	Returns the byte length of the opened, verified source.
const std::filesystem::path &	snapshot_path () const noexcept
	Returns the absolute verified snapshot path actually passed to dlopen().
const std::string &	sha256 () const noexcept
	Returns the observed SHA-256 that matched the expected content before loading.

Static Public Member Functions
static WindowPlanHelper	load (const std::filesystem::path &absolute_path, const std::string &expected_sha256_hex, const std::filesystem::path &private_run_directory)
	Snapshots and hashes an absolute source path before loading any of its code.
static constexpr const char *	self_test_id () noexcept
	Frozen behavior identifier; a later engine behavior change must bump this identifier.

Detailed Description

Owns a verified, privately snapshotted standalone planner library.

Each worker owns one helper and reuses it for all planning calls. Keep this object alive through every call; concurrent calls borrow immutable rows and retain no caller data. Destruction closes the library. Snapshot files, including failed-load snapshots, are left for the assigned run directory's owner to remove after the worker exits. On hash mismatch, the snapshot contains UNVERIFIED bytes that the owner must clean up.

Definition at line 71 of file window_plan.hpp.

Constructor & Destructor Documentation

~WindowPlanHelper()

pineforge::hpo::WindowPlanHelper::~WindowPlanHelper

(

)

Closes the library without deleting the snapshot.

WindowPlanHelper() [1/2]

pineforge::hpo::WindowPlanHelper::WindowPlanHelper ( const WindowPlanHelper &  )

delete

A library owner cannot be copied.

WindowPlanHelper() [2/2]

pineforge::hpo::WindowPlanHelper::WindowPlanHelper ( WindowPlanHelper &&  other )

noexcept

Transfers ownership of the library and snapshot identity.

Member Function Documentation

load()

static WindowPlanHelper pineforge::hpo::WindowPlanHelper::load ( const std::filesystem::path &  absolute_path, const std::string &  expected_sha256_hex, const std::filesystem::path &  private_run_directory  )

static

Snapshots and hashes an absolute source path before loading any of its code.

Parameters

absolute_path	Explicit helper path; relative paths are refused before normalization.
expected_sha256_hex	Expected content SHA-256, exactly 64 lowercase hex characters.
private_run_directory	Existing absolute directory owned by the effective user, with no group/other permissions. Every ancestor must be root- or user-owned and not writable by others unless sticky. Its owner must keep the ancestry stable and leave snapshots untouched throughout the worker lifetime.

Exceptions

TypedHpoError<std::runtime_error>

with hpo_walkforward_unavailable and a reason when snapshotting, identity, binding, version or the frozen self-test fails.

operator=() [1/2]

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

delete

A library owner cannot be copied.

operator=() [2/2]

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

noexcept

Closes the previous library and transfers ownership without deleting either snapshot.

plan_selected_primary()

PlanResult pineforge::hpo::WindowPlanHelper::plan_selected_primary	(	const pf_bar_t *	rows,
		std::size_t	count,
		const PlanRequest &	request
	)		const

Calls the C bridge with exactly rows, without copying or repacking the bar array.

The caller keeps rows immutable and alive until return. Statuses 1..6 are returned as data. Negative bridge returns or malformed result descriptors throw a typed runtime error with reason window_plan_load; they never become successful plans.

self_test_id()

static constexpr const char * pineforge::hpo::WindowPlanHelper::self_test_id ( )

inlinestaticconstexprnoexcept

Frozen behavior identifier; a later engine behavior change must bump this identifier.

Definition at line 121 of file window_plan.hpp.

Referenced by pineforge_hpo.window_plan.WindowPlanIdentity::__post_init__().

sha256()

const std::string & pineforge::hpo::WindowPlanHelper::sha256 ( ) const

inlinenoexcept

Returns the observed SHA-256 that matched the expected content before loading.

Definition at line 119 of file window_plan.hpp.

snapshot_path()

const std::filesystem::path & pineforge::hpo::WindowPlanHelper::snapshot_path ( ) const

inlinenoexcept

Returns the absolute verified snapshot path actually passed to dlopen().

Definition at line 117 of file window_plan.hpp.

source_device()

std::uint64_t pineforge::hpo::WindowPlanHelper::source_device ( ) const

inlinenoexcept

Returns the device of the opened, verified source, even if its pathname was replaced.

Definition at line 111 of file window_plan.hpp.

source_inode()

std::uint64_t pineforge::hpo::WindowPlanHelper::source_inode ( ) const

inlinenoexcept

Returns the inode of the opened, verified source, even if its pathname was replaced.

Definition at line 113 of file window_plan.hpp.

source_path()

const std::filesystem::path & pineforge::hpo::WindowPlanHelper::source_path ( ) const

inlinenoexcept

Returns the absolute source path supplied to load(), for provenance only.

Definition at line 109 of file window_plan.hpp.

source_size()

std::uint64_t pineforge::hpo::WindowPlanHelper::source_size ( ) const

inlinenoexcept

Returns the byte length of the opened, verified source.

Definition at line 115 of file window_plan.hpp.

version()

std::uint32_t pineforge::hpo::WindowPlanHelper::version ( ) const

inlinenoexcept

Returns the validated bridge version, 1.

Definition at line 107 of file window_plan.hpp.

---

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

• window_plan.hpp