Owns and runs the engine's step loop and reports how the run ended. More...

#include <driver.hpp>

Public Types
enum	exitReason_t { winStateFound = 0 , outOfStates = 1 , maximumStepReached = 2 , bestBelowReference = 3 , inputHistoryNearCapacity = 4 }
	Reason the run loop terminated, returned by run. More...

Public Member Functions
	Driver (const std::string &configFilePath, const nlohmann::json &config)
	Constructs the driver and its engine/runner from the parsed configuration.

	~Driver ()
	Destroys the driver.

void	initialize ()
	Resets the execution back to the starting point.

int	run ()
	Runs the engine's step loop until a termination condition is met.

void	storeManualSaveSolution ()
	Saves a solution explicitly requested by the engine, if any.

void	saveBestStateInformation ()
	Writes the current best solution to file, under the mutex.

void	saveWorstStateInformation ()
	Writes the current worst solution to file, under the mutex.

void	intermediateResultSaveLoop ()
	Background loop that periodically saves best and worst solutions to file.

void	updateWorstState ()
	Refreshes the tracked worst state, its solution, and its reward.

void	updateBestState ()
	Refreshes the tracked best state, its solution, and its reward.

void	printInfo ()
	Prints the current state of execution to the logger.

size_t	getCurrentStep ()
	Returns the current step counter.

Static Public Member Functions
static std::unique_ptr< Driver >	getDriver (const std::string &configFilePath, const nlohmann::json &config)
	Factory that constructs a driver from configuration.

Private Attributes
const std::string	_configFilePath
	Path to the config file, kept for reference.

std::unique_ptr< Engine >	_engine
	Pointer to the internal Jaffar engine.

std::unique_ptr< Runner >	_runner
	Runner used for printing information and saving partial results.

size_t	_jobId
	Job identifier (derived from system time) distinguishing intermediate values between jobs.

size_t	_maxSteps
	Maximum number of steps (zero = not established).

size_t	_currentStep
	Counter for the number of steps performed; the initial state counts as step zero.

bool	_endOnFirstWinState
	Whether to end the run on the first win state found.

size_t	_winStatesFound
	Total number of win states found so far.

float	_bestWinStateReward
	Reward for the best win state found so far.

size_t	_bestWinStateStepCount = 0
	Depth of the best win state (recorded at capture; the count is not stored per-state).

size_t	_bestStateStepCount = 0
	Depth of the current best state, set by updateBestState() and reused by the printInfo reload.

float	_bestStateReward
	Ranking reward (magnet-biased) for the best state found so far; drives eviction/display.

float	_bestStateFloorReward
	Un-biased progress (position) reward of the best state; used for the Reference Reward Floor comparison.

float	_worstStateReward
	Reward for the worst state found so far.

bool	_referenceFloorEnabled
	Whether the reference reward floor cancel is active.

float	_referenceFloorTolerance
	Allowed shortfall of best below the reference per step.

std::vector< float >	_referenceReward
	Per-step reference reward floor (index = step).

double	_inputHistoryCapacityWatermark = 0.95
	Fraction of the input-history trie's hard ceiling at which the run stops gracefully (high-water mark).

std::string	_bestStateStorage
	Storage for the current best (win or otherwise) state.

std::string	_worstStateStorage
	Storage for the current worst (win or otherwise) state.

std::string	_bestSolutionStorage
	Storage for the current best solution's input history.

std::string	_worstSolutionStorage
	Storage for the current worst solution's input history.

size_t	_stateSize
	Storage size of a runner state.

__volatile__ bool	_hasFinished
	Internal flag indicating the driver has finished.

bool	_saveIntermediateResultsEnabled
	Whether to store intermediate results at all.

float	_saveIntermediateFrequency
	Minimum interval, in seconds, between intermediate result saves.

std::string	_saveIntermediateBestSolutionPath
	Path to store the best solution found so far.

std::string	_saveIntermediateWorstSolutionPath
	Path to store the worst solution found so far.

std::mutex	_updateIntermediateResultMutex
	Guards intermediate result storage between the main and saver threads.

Detailed Description

Owns and runs the engine's step loop and reports how the run ended.

The driver reads its configuration sections (Driver/Emulator/Game/Runner/Engine), constructs a Runner and an Engine, and repeatedly advances the engine one step at a time until a termination condition is reached (a win state, exhaustion of states, or the maximum step count). On each step it refreshes the tracked best and worst states, optionally stores a manually requested solution, and prints status. A separate thread periodically saves the best and worst solutions to file when intermediate result saving is enabled.

Definition at line 31 of file driver.hpp.

Member Enumeration Documentation

◆ exitReason_t

enum jaffarPlus::Driver::exitReason_t

Reason the run loop terminated, returned by run.

Enumerator
winStateFound	Found a win state.
outOfStates	Engine ran out of states.
maximumStepReached	Maximum step reached.
bestBelowReference	The best state's reward fell below the reference reward floor at this step.
inputHistoryNearCapacity	The shared input-history trie neared/hit its hard memory ceiling.

Definition at line 36 of file driver.hpp.

Constructor & Destructor Documentation

◆ Driver()

jaffarPlus::Driver::Driver	(	const std::string &	configFilePath,
		const nlohmann::json &	config
	)

inline

Constructs the driver and its engine/runner from the parsed configuration.

Reads the "Driver Configuration" section (end-on-first-win flag, max steps, intermediate result settings), derives a job identifier from the current system time, and builds the Runner and Engine from their respective configuration sections.

Parameters

configFilePath	Path to the config file, kept for reference and reporting.
config	Parsed configuration object containing all component sections.

Definition at line 58 of file driver.hpp.

◆ ~Driver()

jaffarPlus::Driver::~Driver ( )

inline

Destroys the driver.

Definition at line 135 of file driver.hpp.

Member Function Documentation

◆ getCurrentStep()

size_t jaffarPlus::Driver::getCurrentStep ( )

inline

Returns the current step counter.

Definition at line 585 of file driver.hpp.

◆ getDriver()

static std::unique_ptr< Driver > jaffarPlus::Driver::getDriver	(	const std::string &	configFilePath,
		const nlohmann::json &	config
	)

inlinestatic

Factory that constructs a driver from configuration.

Parameters

configFilePath	Path to the config file, kept for reference and reporting.
config	Parsed configuration object containing all component sections.

Returns: A unique pointer to the newly constructed Driver.

Definition at line 575 of file driver.hpp.

◆ initialize()

void jaffarPlus::Driver::initialize ( )

inline

Resets the execution back to the starting point.

Clears the step and win-state counters, resets the best/worst reward trackers, initializes the runner and engine, and allocates storage for the current best and worst states.

Definition at line 143 of file driver.hpp.

◆ intermediateResultSaveLoop()

void jaffarPlus::Driver::intermediateResultSaveLoop ( )

inline

Background loop that periodically saves best and worst solutions to file.

Runs while the driver has not finished, waking every 100 ms; once the configured frequency has elapsed since the last save (and at least one step has been performed), it saves the best and worst state information and resets the timer.

Definition at line 377 of file driver.hpp.

◆ printInfo()

void jaffarPlus::Driver::printInfo ( )

inline

Prints the current state of execution to the logger.

Logs the job id, script file, emulator and game names, current/max step, and the best/worst (or win/worst) reward summary, followed by the engine's information and, after loading the best state into the runner, the runner/game/emulator information for that best state.

Definition at line 513 of file driver.hpp.

◆ run()

int jaffarPlus::Driver::run ( )

inline

Runs the engine's step loop until a termination condition is met.

Optionally launches the intermediate result saver thread, then advances the engine one step per iteration, updating the tracked best/worst states, storing any manually requested solution, and printing status each step. The loop ends on the first win state (when so configured), when the engine runs out of states, or when the maximum step count is reached. On exit it joins the saver thread, saves the best state information, and prints a final report.

Returns: The exitReason_t describing why the loop stopped.

Definition at line 182 of file driver.hpp.

◆ saveBestStateInformation()

void jaffarPlus::Driver::saveBestStateInformation ( )

inline

Writes the current best solution to file, under the mutex.

When a best solution path is configured, saves the best solution both under the plain configured name and under a copy suffixed with the job id and current step number.

Definition at line 327 of file driver.hpp.

◆ saveWorstStateInformation()

void jaffarPlus::Driver::saveWorstStateInformation ( )

inline

Writes the current worst solution to file, under the mutex.

When a worst solution path is configured, saves the worst solution both under the plain configured name and under a copy suffixed with the job id.

Definition at line 352 of file driver.hpp.

◆ storeManualSaveSolution()

void jaffarPlus::Driver::storeManualSaveSolution ( )

inline

Saves a solution explicitly requested by the engine, if any.

Queries the engine for a manual-save request; when one has a non-empty path, it loads that state into the runner and writes the runner's input history to the requested file.

Definition at line 304 of file driver.hpp.

◆ updateBestState()

void jaffarPlus::Driver::updateBestState ( )

inline

Refreshes the tracked best state, its solution, and its reward.

Does nothing when the state database is empty and no win states have been found. Otherwise, under the mutex: if no win state has been found yet it uses the engine's current best state; if a win state was found this step and improves on the best win reward so far, it adopts that win state. It then loads the best state into the runner, updates the best-state reward, and records the runner's input history as the best solution.

Definition at line 450 of file driver.hpp.

◆ updateWorstState()

void jaffarPlus::Driver::updateWorstState ( )

inline

Refreshes the tracked worst state, its solution, and its reward.

Does nothing when the state database is empty. Otherwise, under the mutex, copies the engine's worst state into local storage, loads it into the runner, records the runner's input history as the worst solution, and updates the worst-state reward.

Definition at line 412 of file driver.hpp.

Member Data Documentation

◆ _bestSolutionStorage

std::string jaffarPlus::Driver::_bestSolutionStorage

private

Storage for the current best solution's input history.

Definition at line 627 of file driver.hpp.

◆ _bestStateFloorReward

float jaffarPlus::Driver::_bestStateFloorReward

private

Un-biased progress (position) reward of the best state; used for the Reference Reward Floor comparison.

Definition at line 609 of file driver.hpp.

◆ _bestStateReward

float jaffarPlus::Driver::_bestStateReward

private

Ranking reward (magnet-biased) for the best state found so far; drives eviction/display.

Definition at line 608 of file driver.hpp.

◆ _bestStateStepCount

size_t jaffarPlus::Driver::_bestStateStepCount = 0

private

Depth of the current best state, set by updateBestState() and reused by the printInfo reload.

Definition at line 606 of file driver.hpp.

◆ _bestStateStorage

std::string jaffarPlus::Driver::_bestStateStorage

private

Storage for the current best (win or otherwise) state.

Definition at line 623 of file driver.hpp.

◆ _bestWinStateReward

float jaffarPlus::Driver::_bestWinStateReward

private

Reward for the best win state found so far.

Definition at line 604 of file driver.hpp.

◆ _bestWinStateStepCount

size_t jaffarPlus::Driver::_bestWinStateStepCount = 0

private

Depth of the best win state (recorded at capture; the count is not stored per-state).

Definition at line 605 of file driver.hpp.

◆ _configFilePath

const std::string jaffarPlus::Driver::_configFilePath

private

Path to the config file, kept for reference.

Definition at line 588 of file driver.hpp.

◆ _currentStep

size_t jaffarPlus::Driver::_currentStep

private

Counter for the number of steps performed; the initial state counts as step zero.

Definition at line 598 of file driver.hpp.

◆ _endOnFirstWinState

bool jaffarPlus::Driver::_endOnFirstWinState

private

Whether to end the run on the first win state found.

Definition at line 600 of file driver.hpp.

◆ _engine

std::unique_ptr<Engine> jaffarPlus::Driver::_engine

private

Pointer to the internal Jaffar engine.

Definition at line 590 of file driver.hpp.

◆ _hasFinished

__volatile__ bool jaffarPlus::Driver::_hasFinished

private

Internal flag indicating the driver has finished.

Definition at line 633 of file driver.hpp.

◆ _inputHistoryCapacityWatermark

double jaffarPlus::Driver::_inputHistoryCapacityWatermark = 0.95

private

Fraction of the input-history trie's hard ceiling at which the run stops gracefully (high-water mark).

One step's growth (~ live-states nodes) is far below the remaining headroom at this level, so the next per-step check always fires before a worker hits the actual ceiling. Not a config key (sane fixed default); the real lever is Store Input History Type ("Raw" vs "Trie") and the State DB size.

Definition at line 621 of file driver.hpp.

◆ _jobId

size_t jaffarPlus::Driver::_jobId

private

Job identifier (derived from system time) distinguishing intermediate values between jobs.

Definition at line 594 of file driver.hpp.

◆ _maxSteps

size_t jaffarPlus::Driver::_maxSteps

private

Maximum number of steps (zero = not established).

Definition at line 596 of file driver.hpp.

◆ _referenceFloorEnabled

bool jaffarPlus::Driver::_referenceFloorEnabled

private

Whether the reference reward floor cancel is active.

Definition at line 613 of file driver.hpp.

◆ _referenceFloorTolerance

float jaffarPlus::Driver::_referenceFloorTolerance

private

Allowed shortfall of best below the reference per step.

Definition at line 614 of file driver.hpp.

◆ _referenceReward

std::vector<float> jaffarPlus::Driver::_referenceReward

private

Per-step reference reward floor (index = step).

Definition at line 615 of file driver.hpp.

◆ _runner

std::unique_ptr<Runner> jaffarPlus::Driver::_runner

private

Runner used for printing information and saving partial results.

Definition at line 592 of file driver.hpp.

◆ _saveIntermediateBestSolutionPath

std::string jaffarPlus::Driver::_saveIntermediateBestSolutionPath

private

Path to store the best solution found so far.

Definition at line 641 of file driver.hpp.

◆ _saveIntermediateFrequency

float jaffarPlus::Driver::_saveIntermediateFrequency

private

Minimum interval, in seconds, between intermediate result saves.

Definition at line 639 of file driver.hpp.

◆ _saveIntermediateResultsEnabled

bool jaffarPlus::Driver::_saveIntermediateResultsEnabled

private

Whether to store intermediate results at all.

Definition at line 637 of file driver.hpp.

◆ _saveIntermediateWorstSolutionPath

std::string jaffarPlus::Driver::_saveIntermediateWorstSolutionPath

private

Path to store the worst solution found so far.

Definition at line 643 of file driver.hpp.

◆ _stateSize

size_t jaffarPlus::Driver::_stateSize

private

Storage size of a runner state.

Definition at line 631 of file driver.hpp.

◆ _updateIntermediateResultMutex

std::mutex jaffarPlus::Driver::_updateIntermediateResultMutex

private

Guards intermediate result storage between the main and saver threads.

Definition at line 645 of file driver.hpp.

◆ _winStatesFound

size_t jaffarPlus::Driver::_winStatesFound

private

Total number of win states found so far.

Definition at line 602 of file driver.hpp.

◆ _worstSolutionStorage

std::string jaffarPlus::Driver::_worstSolutionStorage

private

Storage for the current worst solution's input history.

Definition at line 629 of file driver.hpp.

◆ _worstStateReward

float jaffarPlus::Driver::_worstStateReward

private

Reward for the worst state found so far.

Definition at line 611 of file driver.hpp.

◆ _worstStateStorage

std::string jaffarPlus::Driver::_worstStateStorage

private

Storage for the current worst (win or otherwise) state.

Definition at line 625 of file driver.hpp.

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

driver.hpp

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ exitReason_t

Constructor & Destructor Documentation

◆ Driver()

◆ ~Driver()

Member Function Documentation

◆ getCurrentStep()

◆ getDriver()

◆ initialize()

◆ intermediateResultSaveLoop()

◆ printInfo()

◆ run()

◆ saveBestStateInformation()

◆ saveWorstStateInformation()

◆ storeManualSaveSolution()

◆ updateBestState()

◆ updateWorstState()

Member Data Documentation

◆ _bestSolutionStorage

◆ _bestStateFloorReward

◆ _bestStateReward

◆ _bestStateStepCount

◆ _bestStateStorage

◆ _bestWinStateReward

◆ _bestWinStateStepCount

◆ _configFilePath

◆ _currentStep

◆ _endOnFirstWinState

◆ _engine

◆ _hasFinished

◆ _inputHistoryCapacityWatermark

◆ _jobId

◆ _maxSteps

◆ _referenceFloorEnabled

◆ _referenceFloorTolerance

◆ _referenceReward

◆ _runner

◆ _saveIntermediateBestSolutionPath

◆ _saveIntermediateFrequency

◆ _saveIntermediateResultsEnabled

◆ _saveIntermediateWorstSolutionPath

◆ _stateSize

◆ _updateIntermediateResultMutex

◆ _winStatesFound

◆ _worstSolutionStorage

◆ _worstStateReward

◆ _worstStateStorage