engine.hpp

Go to the documentation of this file.

#pragma once
 
#include "game.hpp"
#include "hashDb.hpp"
#include "numa.hpp"
#include "runner.hpp"
#include "stateDb.hpp"
#include <algorithm>
#include <emulatorList.hpp>
#include <gameList.hpp>
#include <jaffarCommon/deserializers/base.hpp>
#include <jaffarCommon/hash.hpp>
#include <jaffarCommon/json.hpp>
#include <jaffarCommon/logger.hpp>
#include <jaffarCommon/parallel.hpp>
#include <jaffarCommon/serializers/base.hpp>
#include <jaffarCommon/timing.hpp>
 
// Fine-grained per-operation timing for the engine hot loop. Each timed region costs two
// clock_gettime calls; multiplied across millions of states processed per step this is a real
// overhead for a light emulator (~25% with QuickerSDLPoP), while being negligible under a heavy one
// (QuickerNES is ~92% emulation). It is therefore compiled out unless built with
// -DdetailedProfiling=true. When disabled, JAFFAR_PROF_DECL declares no variable and JAFFAR_PROF_ACC
// is a no-op, so there is neither timing overhead nor an unused-variable warning. The coarse
// per-step timers (step wall time, throughput, serial DB-advance stages) are always kept.
#ifdef JAFFARPLUS_DETAILED_PROFILING
#define JAFFAR_PROF_DECL(var) const auto var = jaffarCommon::timing::now()
#define JAFFAR_PROF_ACC(field, var) field += jaffarCommon::timing::timeDeltaMicroseconds(jaffarCommon::timing::now(), var)
#else
#define JAFFAR_PROF_DECL(var) ((void)0)
#define JAFFAR_PROF_ACC(field, var) ((void)0)
#endif
 
namespace jaffarPlus
{
 
class Engine final
{
public:
  Engine(const nlohmann::json& emulatorConfig, const nlohmann::json& gameConfig, const nlohmann::json& runnerConfig, const nlohmann::json& engineConfig)
  {
    // Initializing NUMA and threading subsystems
    initializeNUMA();
 
    // Sanity check
    if (_threadCount == 0) JAFFAR_THROW_LOGIC("The number of worker threads must be at least one. Provided: %lu\n", _threadCount);
 
    // Printing initial information
    jaffarCommon::logger::log("[J+] Using %lu worker threads.\n", _threadCount);
 
    // Creating storage for the runnners (one per thread)
    _runners.resize(_threadCount);
 
    // Creating runners, one per thread
    JAFFAR_PARALLEL
    {
      // Creating runner from the configuration
      auto r = jaffarPlus::Runner::getRunner(emulatorConfig, gameConfig, runnerConfig);
 
      // Storing runner. Index by the (dense) OpenMP thread id, NOT sched_getcpu(): the latter is only
      // equal to the thread id when threads are pinned 1:1 (OMP_PROC_BIND), and otherwise leaves
      // _runners[0] null -> the *_runners[0] use below (and workerFunction, which already uses the
      // thread id) would dereference a null runner. This bites CI runners that don't pin threads.
      _runners[jaffarCommon::parallel::getThreadId()] = std::move(r);
    }
 
    // Grabbing a runner to do continue build the state databases
    auto& r = *_runners[0];
 
    // Mutable copy so unrecognized Engine keys can be flagged after the known ones are consumed
    auto engineConfigRemaining = engineConfig;
 
    // Creating State database
    auto stateDatabaseJs = jaffarCommon::json::popObject(engineConfigRemaining, "State Database");
    _stateDb             = std::make_unique<jaffarPlus::StateDb>(r, stateDatabaseJs);
 
    // Creating hash database
    auto hashDbConfig = jaffarCommon::json::popObject(engineConfigRemaining, "Hash Database");
    _hashDbEnabled    = jaffarCommon::json::getBoolean(hashDbConfig, "Enabled");
    if (_hashDbEnabled == true) _hashDb = std::make_unique<jaffarPlus::HashDb>(hashDbConfig);
 
    // Base-state pull batch size (per-worker queue-pull granularity). Optional: an explicit value
    // always wins; otherwise 0 here means "auto-tune", resolved in initialize() from the measured
    // per-state cost (light cores -> larger batch to amortize the queue lock; heavy/variable cores
    // -> small batch for load balance).
    _baseStateBatch = engineConfigRemaining.contains("Base State Batch Size") ? jaffarCommon::json::popNumber<size_t>(engineConfigRemaining, "Base State Batch Size") : 0;
    if (_baseStateBatch > BASE_STATE_BATCH_MAX) _baseStateBatch = BASE_STATE_BATCH_MAX;
 
    // Any remaining Engine key is unrecognized
    jaffarCommon::json::checkEmpty(engineConfigRemaining, "Engine Configuration");
 
    // Reserving storage for timing information
    _threadStepTime.resize(_threadCount);
 
    // Reserving per-thread accumulators (cache-line aligned to avoid false sharing).
    // These collect all hot-loop timing/counter increments without atomics, and are
    // reduced into the shared totals once per step (see runStep).
    _threadAccumulators.resize(_threadCount);
  };
 
  void initialize()
  {
    // Initializing state counters
    _totalBaseStatesProcessed = 0;
    _totalNewStatesProcessed  = 0;
 
    // Initializing cumulative timing
    _runnerStateAdvanceAverageCumulativeTime = 0;
    _runnerStateLoadAverageCumulativeTime    = 0;
    _runnerStateSaveAverageCumulativeTime    = 0;
    _calculateHashAverageCumulativeTime      = 0;
    _checkHashAverageCumulativeTime          = 0;
    _ruleCheckingAverageCumulativeTime       = 0;
    _getFreeStateAverageCumulativeTime       = 0;
    _returnFreeStateAverageCumulativeTime    = 0;
    _calculateRewardAverageCumulativeTime    = 0;
    _advanceHashDbAverageCumulativeTime      = 0;
    _getAllowedInputsAverageCumulativeTime   = 0;
    _advanceStateDbAverageCumulativeTime     = 0;
    _popBaseStateDbAverageCumulativeTime     = 0;
 
    // Resetting total running time
    _totalRunningTime = 0;
 
    // Resetting state counts
    _droppedStatesNoStorage           = 0;
    _droppedStatesFailedSerialization = 0;
    _droppedStatesCheckpoint          = 0;
    _repeatedStates                   = 0;
    _failedStates                     = 0;
    _winStates                        = 0;
    _normalStates                     = 0;
 
    // Resetting checkpoint counters
    _checkpointLevel     = 0;
    _checkpointTolerance = 0;
    _checkpointCutoff    = 0;
 
    // Resetting counter for the current step
    _currentStep = 0;
 
    // Resetting last active manually solution save rule id
    _manualSaveSolutionActiveLastRuleId = -1;
 
    // Create the one shared input-history backing (e.g. the trie, for the "Trie" strategy; null for
    // raw/none) and inject it into every worker runner BEFORE they initialize, so all workers share it.
    // It is sized with one free-list shard per worker thread plus one for the driver's intermediate-result
    // thread (contention-free alloc/free). The StateDb reaches the strategy via the reference runner.
    _inputHistoryBacking = inputHistory::createSharedBacking(_runners[0]->getInputHistoryConfig(), _threadCount + 1);
 
    // Initializing runners, one per thread
    JAFFAR_PARALLEL
    {
      // Creating thread's own runner (index by OpenMP thread id, consistent with construction/workerFunction)
      auto& r = _runners[jaffarCommon::parallel::getThreadId()];
 
      // Share the one backing (prefix sharing) and give each worker its own free-list shard (its thread id).
      r->setInputHistoryBacking(_inputHistoryBacking, (uint32_t)jaffarCommon::parallel::getThreadId(), _threadCount + 1);
      r->initialize();
    }
 
    // Combined RAM guard: the per-NUMA check inside StateDb::initialize() validates ONLY the state
    // DB, and the hash DB's peak footprint is (Max Store Size x Max Store Count) -- NOT just Max Store
    // Size. Summing both against total free RAM here catches a silent overcommit that the OS would
    // otherwise resolve by OOM-killing the process mid-run (hours in). Done before any DB allocates.
    {
      const size_t stateBudget = _stateDb->getMaxBudgetBytes();
      const size_t hashBudget  = (_hashDbEnabled == true) ? _hashDb->getMaxBudgetBytes() : 0;
      // Shared input-history trie: an uncounted structure that grows ~ live-states x depth up to its hard
      // node cap (~384 GiB for the Trie strategy on this build). Reserve its ceiling. (0 for None/Raw.)
      const size_t historyBound = inputHistory::getSharedBackingMaxMemoryBytes(_inputHistoryBacking);
      // The state DB is a fixed pool (1x; full slots are scavenged from the current step, never doubled).
      // The hash DB phmap grows by doubling, so during a rehash the old table and the new 2x table briefly
      // coexist -- reserve ~2x the hash budget for that transient. (Empirically a 270 GB state+hash config
      // peaked at ~520 GB RSS = state + ~2*hash + trie, then OOM-killed mid-run.)
      const size_t hashPeak    = hashBudget * 2;
      const size_t totalBudget = stateBudget + hashPeak + historyBound;
      size_t       freeRam     = 0;
      for (int i = 0; i < _numaCount; i++)
      {
        long long nodeFree = 0;
        numa_node_size64(i, &nodeFree);
        freeRam += (size_t)nodeFree;
      }
      const size_t usable = (size_t)((double)freeRam * 0.90); // 10% headroom: emulators, OS, fragmentation
      if (totalBudget > usable)
      {
        const double GB = 1024.0 * 1024.0 * 1024.0;
        JAFFAR_THROW_RUNTIME("Configured database budget exceeds available memory:\n"
                             "  State DB ('Max Size (Mb)', fixed pool)                       = %.1f GB\n"
                             "  Hash DB peak (2 x 'Max Store Size' x 'Max Store Count')      = %.1f GB\n"
                             "  Input-history trie (hard node-storage ceiling)               = %.1f GB\n"
                             "  TOTAL                                                        = %.1f GB\n"
                             "  Usable (90%% of %.1f GB free RAM)                             = %.1f GB\n"
                             "Reduce 'State Database/Max Size (Mb)' and/or 'Hash Database/Max Store Size (Mb)'.\n"
                             "NOTE: the hash DB phmap doubles on growth, so a rehash briefly holds the old + new (2x) table; the\n"
                             "Trie input-history is a separate structure that grows up to ~384 GiB. Both are otherwise uncounted.\n",
                             (double)stateBudget / GB, (double)hashPeak / GB, (double)historyBound / GB, (double)totalBudget / GB, (double)freeRam / GB, (double)usable / GB);
      }
    }
 
    // Initializing State Db
    _stateDb->initialize();
 
    // Initializing hash database
    if (_hashDbEnabled == true) _hashDb->initialize();
 
    // Grabbing a runner to do continue initialization
    auto& r = *_runners[0];
 
    // Auto-tune the base-state pull batch (when "Base State Batch Size" was not set in the config).
    // We time a burst of state advances on the (just-loaded) initial state -- which is representative
    // of the core's per-state cost -- then choose a batch so each batch is ~TARGET_BATCH_NS of work:
    // enough to amortize the per-NUMA queue lock on cheap cores (large batch) while keeping a small
    // batch on heavy/variable cores so end-of-step load imbalance stays low. The measurement state is
    // saved and restored so the search still starts from the exact initial state. Batch size never
    // affects which states are explored, only the work distribution.
    if (_baseStateBatch == 0)
    {
      const size_t      stateSize = r.getStateSize();
      std::vector<char> scratch(stateSize);
      {
        jaffarCommon::serializer::Contiguous s(scratch.data(), stateSize);
        r.serializeState(s);
      }
 
      const auto                   allowedInputs = r.getAllowedInputs();
      const InputSet::inputIndex_t calInput      = allowedInputs.empty() ? (InputSet::inputIndex_t)0 : allowedInputs[0];
 
      const size_t CAL_FRAMES = 200;
      const auto   tCal0      = jaffarCommon::timing::now();
      for (size_t i = 0; i < CAL_FRAMES; i++) r.advanceState(calInput);
      const size_t perStateNs = jaffarCommon::timing::timeDeltaNanoseconds(jaffarCommon::timing::now(), tCal0) / CAL_FRAMES;
 
      // Restore the exact initial state
      {
        jaffarCommon::deserializer::Contiguous d(scratch.data(), stateSize);
        r.deserializeState(d);
      }
 
      // ~200us of work per batch: SDLPoP (~10us/state) -> ~16, Genesis (~600us/state) -> 1.
      constexpr size_t TARGET_BATCH_NS = 200000;
      size_t           b               = (perStateNs > 0) ? ((TARGET_BATCH_NS + perStateNs / 2) / perStateNs) : BASE_STATE_BATCH_MAX;
      if (b < 1) b = 1;
      if (b > BASE_STATE_BATCH_MAX) b = BASE_STATE_BATCH_MAX;
      _baseStateBatch = b;
      jaffarCommon::logger::log("[J+] Auto-tuned base-state batch size:            %lu (measured %.1f us/state)\n", _baseStateBatch, (double)perStateNs / 1000.0);
    }
    if (_baseStateBatch < 1) _baseStateBatch = 1;
 
    // Evaluate game rules on the initial state
    r.getGame()->evaluateRules();
 
    // Determining new game state type
    r.getGame()->updateGameStateType();
 
    // Running game-specific rule actions
    r.getGame()->runGameSpecificRuleActions();
 
    // Updating game reward
    r.getGame()->updateReward();
 
    // Getting reward for the initial state
    const auto reward = r.getGame()->getReward();
 
    // Getting a free state data pointer to store the state into (serial init path -> thread 0)
    auto stateData = _stateDb->getFreeState(0);
 
    // Pushing initial state to the next state database
    _stateDb->pushState(reward, r, stateData);
 
    // Advancing the step in the state database
    _stateDb->advanceStep();
 
    // Getting memory for the reference state
    _stateSizeInDatabase = _stateDb->getStateSizeInDatabase();
 
    // Standalone snapshots hold the FULL self-contained state ([hot][history]); the DB slot is hot-only.
    _fullStateSize = _stateDb->getFullStateSize();
 
    // Allocating memory for the best win state
    _stepBestWinState.stateData = malloc(_fullStateSize);
 
    // Allocating memory for manual state saving
    _manualSaveSolution.stateData = malloc(_fullStateSize);
 
    // Getting hash from first state
    const auto hash = r.computeHash();
 
    // Adding it to the hash DB
    if (_hashDbEnabled == true) _hashDb->insertHash(hash);
  }
 
  void runStep()
  {
    // Computing step time
    const auto tStep = jaffarCommon::timing::now();
 
    // Clearing step timing for the serially-measured stages (the rest are reduced
    // from the per-thread accumulators after the parallel region)
    _advanceHashDbThreadRawTime  = 0;
    _advanceStateDbThreadRawTime = 0;
 
    // Resetting per-thread accumulators for this step
    for (ssize_t i = 0; i < _threadCount; i++) _threadAccumulators[i].reset();
 
    // Clearing win state reward
    _stepBestWinState.reward = -std::numeric_limits<float>::infinity();
 
    // Clearing manually saved state
    _manualSaveSolution.reward      = -std::numeric_limits<float>::infinity();
    _manualSaveSolution.path        = "";
    _manualSaveSolution.lastRuleIdx = -1;
 
    // (Manual solution storing) Resetting last active rule id flag
    _manualSaveSolutionUpdatedLastRuleId = false;
 
    // Performing one computation step in parallel
    JAFFAR_PARALLEL
    workerFunction();
 
    // Reducing per-thread accumulators into the shared totals (serial, ~threadCount adds).
    // The per-step raw timers and step counters are zeroed here, then summed; the
    // run-long state-type counters keep accumulating across steps.
    _runnerStateAdvanceThreadRawTime = 0;
    _runnerStateLoadThreadRawTime    = 0;
    _runnerStateSaveThreadRawTime    = 0;
    _calculateHashThreadRawTime      = 0;
    _checkHashThreadRawTime          = 0;
    _ruleCheckingThreadRawTime       = 0;
    _getFreeStateThreadRawTime       = 0;
    _returnFreeStateThreadRawTime    = 0;
    _calculateRewardThreadRawTime    = 0;
    _getAllowedInputsThreadRawTime   = 0;
    _getCandidateInputsThreadRawTime = 0;
    _popBaseStateDbThreadRawTime     = 0;
    _stepBaseStatesProcessed         = 0;
    _stepNewStatesProcessed          = 0;
    for (ssize_t i = 0; i < _threadCount; i++)
    {
      const auto& a = _threadAccumulators[i];
      _runnerStateAdvanceThreadRawTime += a.runnerStateAdvance;
      _runnerStateLoadThreadRawTime += a.runnerStateLoad;
      _runnerStateSaveThreadRawTime += a.runnerStateSave;
      _calculateHashThreadRawTime += a.calculateHash;
      _checkHashThreadRawTime += a.checkHash;
      _ruleCheckingThreadRawTime += a.ruleChecking;
      _getFreeStateThreadRawTime += a.getFreeState;
      _returnFreeStateThreadRawTime += a.returnFreeState;
      _calculateRewardThreadRawTime += a.calculateReward;
      _getAllowedInputsThreadRawTime += a.getAllowedInputs;
      _getCandidateInputsThreadRawTime += a.getCandidateInputs;
      _popBaseStateDbThreadRawTime += a.popBaseStateDb;
      _stepBaseStatesProcessed += a.baseStatesProcessed;
      _stepNewStatesProcessed += a.newStatesProcessed;
      _normalStates += a.normalStates;
      _repeatedStates += a.repeatedStates;
      _failedStates += a.failedStates;
      _winStates += a.winStates;
      _droppedStatesNoStorage += a.droppedStatesNoStorage;
      _droppedStatesFailedSerialization += a.droppedStatesFailedSerialization;
      _droppedStatesCheckpoint += a.droppedStatesCheckpoint;
    }
 
    // Advancing hash database state
    const auto t0 = jaffarCommon::timing::now();
    if (_hashDbEnabled == true) _hashDb->advanceStep();
    _advanceHashDbThreadRawTime += jaffarCommon::timing::timeDeltaMicroseconds(jaffarCommon::timing::now(), t0);
 
    // Swapping next and current state databases
    const auto t1 = jaffarCommon::timing::now();
    _stateDb->advanceStep();
    _advanceStateDbThreadRawTime += jaffarCommon::timing::timeDeltaMicroseconds(jaffarCommon::timing::now(), t1);
 
    // Updating last active last rule Id
    if (_manualSaveSolutionUpdatedLastRuleId)
    {
      _manualSaveSolutionActiveLastRuleId = _manualSaveSolution.lastRuleIdx;
      _manualSaveSolutionLastPath         = _manualSaveSolution.path;
    }
 
    // Computing step time
    _currentStepTime = jaffarCommon::timing::timeDeltaMicroseconds(jaffarCommon::timing::now(), tStep);
 
    // Computing total running time
    _totalRunningTime += _currentStepTime;
 
    // Getting maximum thread step time
    _maxThreadStepTimeThreadId = 0;
    _maxThreadStepTime         = _threadStepTime[0];
    for (ssize_t i = 0; i < _threadCount; i++)
      if (_threadStepTime[i] > _maxThreadStepTime)
      {
        _maxThreadStepTimeThreadId = i;
        _maxThreadStepTime         = _threadStepTime[i];
      }
 
    // Processing thread-average step timing
    _runnerStateAdvanceAverageTime = _runnerStateAdvanceThreadRawTime / _threadCount;
    _runnerStateLoadAverageTime    = _runnerStateLoadThreadRawTime / _threadCount;
    _runnerStateSaveAverageTime    = _runnerStateSaveThreadRawTime / _threadCount;
    _calculateHashAverageTime      = _calculateHashThreadRawTime / _threadCount;
    _checkHashAverageTime          = _checkHashThreadRawTime / _threadCount;
    _ruleCheckingAverageTime       = _ruleCheckingThreadRawTime / _threadCount;
    _getFreeStateAverageTime       = _getFreeStateThreadRawTime / _threadCount;
    _returnFreeStateAverageTime    = _returnFreeStateThreadRawTime / _threadCount;
    _calculateRewardAverageTime    = _calculateRewardThreadRawTime / _threadCount;
    _popBaseStateDbAverageTime     = _popBaseStateDbThreadRawTime / _threadCount;
    _getAllowedInputsAverageTime   = _getAllowedInputsThreadRawTime / _threadCount;
    _getCandidateInputsAverageTime = _getCandidateInputsThreadRawTime / _threadCount;
    _advanceHashDbAverageTime      = _advanceHashDbThreadRawTime.load();
    _advanceStateDbAverageTime     = _advanceStateDbThreadRawTime.load();
 
    // Sub-total thread-average step timing
    _subTotalAverageTime = 0;
    _subTotalAverageTime += _runnerStateAdvanceAverageTime;
    _subTotalAverageTime += _runnerStateLoadAverageTime;
    _subTotalAverageTime += _runnerStateSaveAverageTime;
    _subTotalAverageTime += _calculateHashAverageTime;
    _subTotalAverageTime += _checkHashAverageTime;
    _subTotalAverageTime += _ruleCheckingAverageTime;
    _subTotalAverageTime += _getFreeStateAverageTime;
    _subTotalAverageTime += _returnFreeStateAverageTime;
    _subTotalAverageTime += _calculateRewardAverageTime;
    _subTotalAverageTime += _getAllowedInputsAverageTime;
    _subTotalAverageTime += _getCandidateInputsAverageTime;
    _subTotalAverageTime += _popBaseStateDbAverageTime;
    _subTotalAverageTime += _advanceHashDbAverageTime;
    _subTotalAverageTime += _advanceStateDbAverageTime;
 
    // Processing cumulative timing
    _runnerStateAdvanceAverageCumulativeTime += _runnerStateAdvanceAverageTime;
    _runnerStateLoadAverageCumulativeTime += _runnerStateLoadAverageTime;
    _runnerStateSaveAverageCumulativeTime += _runnerStateSaveAverageTime;
    _calculateHashAverageCumulativeTime += _calculateHashAverageTime;
    _checkHashAverageCumulativeTime += _checkHashAverageTime;
    _ruleCheckingAverageCumulativeTime += _ruleCheckingAverageTime;
    _getFreeStateAverageCumulativeTime += _getFreeStateAverageTime;
    _returnFreeStateAverageCumulativeTime += _returnFreeStateAverageTime;
    _calculateRewardAverageCumulativeTime += _calculateRewardAverageTime;
    _popBaseStateDbAverageCumulativeTime += _popBaseStateDbAverageTime;
    _getAllowedInputsAverageCumulativeTime += _getAllowedInputsAverageTime;
    _getCandidateInputsAverageCumulativeTime += _getCandidateInputsAverageTime;
    _advanceHashDbAverageCumulativeTime += _advanceHashDbAverageTime;
    _advanceStateDbAverageCumulativeTime += _advanceStateDbAverageTime;
 
    // Sub-total cumulative time calculation
    _subTotalAverageCumulativeTime = 0;
    _subTotalAverageCumulativeTime += _runnerStateAdvanceAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _runnerStateLoadAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _runnerStateSaveAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _calculateHashAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _checkHashAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _ruleCheckingAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _getFreeStateAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _returnFreeStateAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _calculateRewardAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _popBaseStateDbAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _getAllowedInputsAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _getCandidateInputsAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _advanceHashDbAverageCumulativeTime;
    _subTotalAverageCumulativeTime += _advanceStateDbAverageCumulativeTime;
 
    // Processing state counters
    _totalBaseStatesProcessed += _stepBaseStatesProcessed;
    _totalNewStatesProcessed += _stepNewStatesProcessed;
 
    // Advancing step
    _currentStep++;
  }
 
  ~Engine()
  {
    // Free the state buffers allocated in initialize() (raw malloc; see _stateSizeInDatabase use above)
    free(_stepBestWinState.stateData);
    free(_manualSaveSolution.stateData);
  }
 
  // Relevant data for the driver
 
  auto& getStateDb() const { return _stateDb; }
  auto getStepBestWinState() const { return _stepBestWinState; }
  auto getManualSaveSolution() const { return _manualSaveSolution; }
  auto getWinStatesFound() const { return _winStates.load(); }
  auto getStateCount() const { return _stateDb->getStateCount(); }
 
  size_t getInputHistoryMaxMemoryBytes() const { return inputHistory::getSharedBackingMaxMemoryBytes(_inputHistoryBacking); }
  size_t getInputHistoryApproxMemoryBytes() const { return inputHistory::getSharedBackingApproxMemoryBytes(_inputHistoryBacking); }
  bool isInputHistoryExhausted() const { return inputHistory::isSharedBackingExhausted(_inputHistoryBacking); }
 
  void printInfo()
  {
    // Printing information
    jaffarCommon::logger::log("[J+] Thread Count / NUMA Domains:                 %3d / %d\n", _threadCount, _numaCount);
#ifdef JAFFARPLUS_DETAILED_PROFILING
    jaffarCommon::logger::log("[J+] Elapsed Time (Step/Total):                   %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_currentStepTime),
                              100.0 * ((double)(_subTotalAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_totalRunningTime),
                              100.0 * ((double)_subTotalAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Runner State Avance (Step/Total):         %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_runnerStateAdvanceAverageTime),
                              100.0 * ((double)(_runnerStateAdvanceAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_runnerStateAdvanceAverageCumulativeTime),
                              100.0 * ((double)_runnerStateAdvanceAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Runner State Load (Step/Total):           %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_runnerStateLoadAverageTime),
                              100.0 * ((double)(_runnerStateLoadAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_runnerStateLoadAverageCumulativeTime),
                              100.0 * ((double)_runnerStateLoadAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Runner State Save (Step/Total):           %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_runnerStateSaveAverageTime),
                              100.0 * ((double)(_runnerStateSaveAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_runnerStateSaveAverageCumulativeTime),
                              100.0 * ((double)_runnerStateSaveAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Hash Calculation (Step/Total):            %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_calculateHashAverageTime),
                              100.0 * ((double)(_calculateHashAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_calculateHashAverageCumulativeTime),
                              100.0 * ((double)_calculateHashAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Hash Checking (Step/Total):               %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_checkHashAverageTime),
                              100.0 * ((double)(_checkHashAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_checkHashAverageCumulativeTime),
                              100.0 * ((double)_checkHashAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Rule Checking (Step/Total):               %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_ruleCheckingAverageTime),
                              100.0 * ((double)(_ruleCheckingAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_ruleCheckingAverageCumulativeTime),
                              100.0 * ((double)_ruleCheckingAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Get Free State (Step/Total):              %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_getFreeStateAverageTime),
                              100.0 * ((double)(_getFreeStateAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_getFreeStateAverageCumulativeTime),
                              100.0 * ((double)_getFreeStateAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Return Free State (Step/Total):           %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_returnFreeStateAverageTime),
                              100.0 * ((double)(_returnFreeStateAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_returnFreeStateAverageCumulativeTime),
                              100.0 * ((double)_returnFreeStateAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Calculate Reward (Step/Total):            %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_calculateRewardAverageTime),
                              100.0 * ((double)(_calculateRewardAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_calculateRewardAverageCumulativeTime),
                              100.0 * ((double)_calculateRewardAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Popping Base State (Step/Total):          %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_popBaseStateDbAverageTime),
                              100.0 * ((double)(_popBaseStateDbAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_popBaseStateDbAverageCumulativeTime),
                              100.0 * ((double)_popBaseStateDbAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Get Allowed Inputs (Step/Total):          %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_getAllowedInputsAverageTime),
                              100.0 * ((double)(_getAllowedInputsAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_getAllowedInputsAverageCumulativeTime),
                              100.0 * ((double)_getAllowedInputsAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Get Candidate Inputs (Step/Total):        %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_getCandidateInputsAverageTime),
                              100.0 * ((double)(_getCandidateInputsAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_getCandidateInputsAverageCumulativeTime),
                              100.0 * ((double)_getCandidateInputsAverageCumulativeTime) / (double)(_totalRunningTime));
#else
    // Detailed per-operation profiling is compiled out (default). Only the coarse step wall time and
    // the serially-measured DB-advance stages below are available; build -DdetailedProfiling=true for
    // the full per-operation breakdown.
    jaffarCommon::logger::log("[J+] Elapsed Time (Step/Total):                   %9.3fs / %9.3fs   (per-operation breakdown disabled; build -DdetailedProfiling=true)\n",
                              1.0e-6 * (double)(_currentStepTime), 1.0e-6 * (double)(_totalRunningTime));
#endif
 
    jaffarCommon::logger::log("[J+]  + Advance Hash Db (Step/Total):             %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_advanceHashDbAverageTime),
                              100.0 * ((double)(_advanceHashDbAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_advanceHashDbAverageCumulativeTime),
                              100.0 * ((double)_advanceHashDbAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+]  + Advance State Db (Step/Total):            %9.3fs (%7.3f%%) / %9.3fs (%3.3f%%)\n", 1.0e-6 * (double)(_advanceStateDbAverageTime),
                              100.0 * ((double)(_advanceStateDbAverageTime) / (double)(_currentStepTime)), 1.0e-6 * (double)(_advanceStateDbAverageCumulativeTime),
                              100.0 * ((double)_advanceStateDbAverageCumulativeTime) / (double)(_totalRunningTime));
 
    jaffarCommon::logger::log("[J+] Checkpoint (Level/Tolerance/Cutoff):         %lu / %lu / %lu\n", _checkpointLevel, _checkpointTolerance, _checkpointCutoff);
    jaffarCommon::logger::log("[J+] Base States Processed:                       %.3f Mstates (Total: %.3f Mstates)\n", 1.0e-6 * (double)_stepBaseStatesProcessed,
                              1.0e-6 * (double)_totalBaseStatesProcessed);
    jaffarCommon::logger::log("[J+] New States Processed:                        %.3f Mstates (Total: %.3f Mstates)\n", 1.0e-6 * (double)_stepNewStatesProcessed,
                              1.0e-6 * (double)_totalNewStatesProcessed);
 
    jaffarCommon::logger::log("[J+] Base States Performance:                     %.3f Mstates/s (Average: %.3f Mstates/s)\n",
                              1.0e-6 * (double)_stepBaseStatesProcessed / (1.0e-6 * (double)_currentStepTime),
                              1.0e-6 * (double)_totalBaseStatesProcessed / (1.0e-6 * (double)_totalRunningTime));
    jaffarCommon::logger::log("[J+] New States Performance:                      %.3f Mstates/s (Average: %.3f Mstates/s)\n",
                              1.0e-6 * (double)_stepNewStatesProcessed / (1.0e-6 * (double)_currentStepTime),
                              1.0e-6 * (double)_totalNewStatesProcessed / (1.0e-6 * (double)_totalRunningTime));
 
    jaffarCommon::logger::log("[J+] Dropped States (No Storage Available):       %lu (%5.3f%% of New States Processed) \n", _droppedStatesNoStorage.load(),
                              100.0 * (double)_droppedStatesNoStorage.load() / (double)_totalNewStatesProcessed);
    jaffarCommon::logger::log("[J+] Dropped States (Failed Serialization):       %lu (%5.3f%% of New States Processed) \n", _droppedStatesFailedSerialization.load(),
                              100.0 * (double)_droppedStatesFailedSerialization.load() / (double)_totalNewStatesProcessed);
    jaffarCommon::logger::log("[J+] Dropped States (Checkpoint):                 %lu (%5.3f%% of New States Processed) \n", _droppedStatesCheckpoint.load(),
                              100.0 * (double)_droppedStatesCheckpoint.load() / (double)_totalNewStatesProcessed);
    jaffarCommon::logger::log("[J+] Failed States:                               %lu (%5.3f%% of New States Processed) \n", _failedStates.load(),
                              100.0 * (double)_failedStates.load() / (double)_totalNewStatesProcessed);
    jaffarCommon::logger::log("[J+] Repeated States:                             %lu (%5.3f%% of New States Processed) \n", _repeatedStates.load(),
                              100.0 * (double)_repeatedStates.load() / (double)_totalNewStatesProcessed);
    jaffarCommon::logger::log("[J+] Normal States:                               %lu (%5.3f%% of New States Processed) \n", _normalStates.load(),
                              100.0 * (double)_normalStates.load() / (double)_totalNewStatesProcessed);
    jaffarCommon::logger::log("[J+] Win States:                                  %lu (%5.3f%% of New States Processed) \n", _winStates.load(),
                              100.0 * (double)_winStates.load() / (double)_totalNewStatesProcessed);
 
    // Print state database information
    jaffarCommon::logger::log("[J+] State Database Information:\n");
    _stateDb->printInfo();
 
    if (_hashDbEnabled == true)
    {
      jaffarCommon::logger::log("[J+] Hash Database Information:\n");
      _hashDb->printInfo();
    }
 
    jaffarCommon::logger::log("[J+] Manually Saved Solution:\n");
    jaffarCommon::logger::log("[J+]   + Path:                                    '%s'\n", _manualSaveSolution.path.c_str());
    jaffarCommon::logger::log("[J+]   + Reward:                                  %f\n", _manualSaveSolution.reward);
    jaffarCommon::logger::log("[J+]   + Last Rule Idx:                           %ld (Active: %ld, Path: '%s')\n", _manualSaveSolution.lastRuleIdx,
                              _manualSaveSolutionActiveLastRuleId, _manualSaveSolutionLastPath.c_str());
 
    // Printing candidate inpts
    jaffarCommon::logger::log("[J+] Candidate Inputs:\n");
    for (const auto& entry : _candidateInputsDetected)
    {
      jaffarCommon::logger::log("[J+]  + Hash:                                     %s\n", jaffarCommon::hash::hashToString(entry.first).c_str());
      for (const auto input : entry.second) jaffarCommon::logger::log("[J+]    + %3lu %s\n", input, _runners[0]->getInputStringFromIndex(input).c_str());
    }
  }
 
  __INLINE__ size_t getStateSizeInDatabase() const { return _stateSizeInDatabase; }
 
  __INLINE__ size_t getFullStateSize() const { return _fullStateSize; }
 
private:
  // Number of base states a worker pulls from the shared per-NUMA state-DB queue per lock
  // acquisition (into a thread-local buffer), instead of locking once per state. On a light
  // emulator with dozens of worker threads per NUMA domain, that single-state lock/unlock was the
  // dominant cost ("Popping Base State" ~37% of wall time); batching collapses it to <0.5%.
  //
  // The value is empirically tuned (EPYC 9755, 256 threads, SDLPoP lvl01): throughput is flat-
  // optimal across 4-16 and falls off above it (32 ~ -4%, 64 ~ -10%, 512 ~ -9%). The reason is that
  // once the lock contention is gone, the dominant effect is intra-step load balancing across 256
  // threads -- a larger batch lets one straggler hold many states while others see the queue drain
  // and go idle. 16 sits at the top of the flat region while keeping enough amortization headroom to
  // stay robust for workloads with cheaper per-state work or higher thread counts. (A page-sized
  // batch of 512 pointers was tried, on the theory the buffer would be cache/TLB friendly, but the
  // buffer is tiny and L1-resident at any of these sizes, so the load-imbalance cost dominated.)
  // The batch size is configurable ("Base State Batch Size"); when unset it comes from the
  // emulator's getSuggestedStateBatchSize() (heavy cores 1 for load balance, light cores ~16 to
  // amortize the queue lock). BASE_STATE_BATCH_MAX bounds the thread-local pull buffer; the active
  // count is _baseStateBatch (clamped to [1, MAX]).
  static constexpr size_t BASE_STATE_BATCH_MAX = 16;
 
  enum inputResult_t
  {
    repeated,                   
    droppedNoStorage,           
    droppedFailedSerialization, 
    droppedCheckpoint,          
    failed,                     
    normal,                     
    win                         
  };
 
  struct stateInfo_t
  {
    float  reward;              
    void*  stateData = nullptr; 
    size_t stepCount = 0;       
  };
 
  struct manualSaveSolution_t
  {
    std::string path;                
    float       reward;              
    void*       stateData = nullptr; 
    ssize_t     lastRuleIdx;         
    size_t      stepCount = 0;       
  };
 
  struct alignas(64) threadAccumulator_t
  {
    // Timers (microseconds)
    size_t runnerStateAdvance; 
    size_t runnerStateLoad;    
    size_t runnerStateSave;    
    size_t calculateHash;      
    size_t checkHash;          
    size_t ruleChecking;       
    size_t getFreeState;       
    size_t returnFreeState;    
    size_t calculateReward;    
    size_t getAllowedInputs;   
    size_t getCandidateInputs; 
    size_t popBaseStateDb;     
 
    // Counters
    size_t baseStatesProcessed;              
    size_t newStatesProcessed;               
    size_t normalStates;                     
    size_t repeatedStates;                   
    size_t failedStates;                     
    size_t winStates;                        
    size_t droppedStatesNoStorage;           
    size_t droppedStatesFailedSerialization; 
    size_t droppedStatesCheckpoint;          
 
    __INLINE__ void reset() { *this = threadAccumulator_t{}; }
  };
 
  void workerFunction()
  {
    // Getting my thread id
    const auto threadId = jaffarCommon::parallel::getThreadId();
 
    // Getting my thread-local accumulator (no atomics in the hot path)
    auto& acc = _threadAccumulators[threadId];
 
    // Starting to measure thread-specific step time
    const auto threadTime0 = jaffarCommon::timing::now();
 
    // Getting my runner
    auto& r = _runners[threadId];
 
    // Base states are pulled from the database in batches into this thread-local buffer, so the
    // shared per-NUMA queue lock is acquired once per BASE_STATE_BATCH states instead of once per
    // state. With many worker threads per NUMA domain and cheap per-state work, the single-state
    // lock/unlock dominates wall time ("Popping Base State"); batching amortizes it away.
    void* baseStateBatch[BASE_STATE_BATCH_MAX];
    JAFFAR_PROF_DECL(t);
    size_t batchCount = _stateDb->popStates(baseStateBatch, _baseStateBatch, threadId);
    JAFFAR_PROF_ACC(acc.popBaseStateDb, t);
    size_t batchIdx = 0;
 
    // While there are still states in the database, keep on grabbing them
    while (batchIdx < batchCount)
    {
      // Taking the next base state from the local batch
      void* baseStateData = baseStateBatch[batchIdx++];
 
      // Increasing base state counter
      acc.baseStatesProcessed++;
 
      // Load state into runner via the state database (base states are slab slots: hot slot + cold path)
      JAFFAR_PROF_DECL(t0);
      _stateDb->loadStateFromSlot(*r, baseStateData);
      r->setSearchStep(_currentStep); // base state's depth = current search step (count is not stored per-state)
      JAFFAR_PROF_ACC(acc.runnerStateLoad, t0);
 
      // Getting allowed inputs
      JAFFAR_PROF_DECL(t1);
      const auto allowedInputs = r->getAllowedInputs();
      JAFFAR_PROF_ACC(acc.getAllowedInputs, t1);
 
      // Getting candidate inputs (those not already covered by the allowed set). Computed here,
      // before the allowed inputs are tried, while the runner still holds the unperturbed base state.
      JAFFAR_PROF_DECL(t2);
      auto candidateInputs = r->getCandidateInputs();
      JAFFAR_PROF_ACC(acc.getCandidateInputs, t2);
 
      // Finding unique candidate inputs
      std::vector<InputSet::inputIndex_t> uniqueCandidateInputs;
      for (const auto& input : candidateInputs)
        if (std::find(allowedInputs.begin(), allowedInputs.end(), input) == allowedInputs.end()) uniqueCandidateInputs.push_back(input);
 
      // Discriminating hash of the *base* state (the situation being expanded), used to dedup
      // candidate-input probing across like states. It must be taken from the base state, so it is
      // captured now -- before the allowed/candidate inputs below advance the runner away from it.
      jaffarCommon::hash::hash_t baseStateInputHash{};
      if (uniqueCandidateInputs.empty() == false) baseStateInputHash = r->getGame()->getStateInputHash();
 
      // Trying out each possible input in the set
      for (auto inputItr = allowedInputs.begin(); inputItr != allowedInputs.end(); inputItr++) runNewInput(*r, baseStateData, *inputItr, acc, threadId);
 
      // Run each candidate input, keyed by the base state's discriminating hash
      for (const auto input : uniqueCandidateInputs)
      {
        // Making sure we don't try the input if it was already detected for this type of state
        if (_candidateInputsDetected.contains(baseStateInputHash))
          if (_candidateInputsDetected[baseStateInputHash].contains(input)) continue;
 
        // Running input
        const auto result = runNewInput(*r, baseStateData, input, acc, threadId);
 
        // If this is not a repeated state, store it as new candidate input
        if (result != inputResult_t::repeated) _candidateInputsDetected[baseStateInputHash].insert(input);
      }
 
      // Return base state to the free state queue
      JAFFAR_PROF_DECL(t8);
      _stateDb->returnFreeState(baseStateData, threadId);
      JAFFAR_PROF_ACC(acc.returnFreeState, t8);
 
      // When the local batch is exhausted, pull the next batch from the database
      if (batchIdx >= batchCount)
      {
        JAFFAR_PROF_DECL(t9);
        batchCount = _stateDb->popStates(baseStateBatch, _baseStateBatch, threadId);
        JAFFAR_PROF_ACC(acc.popBaseStateDb, t9);
        batchIdx = 0;
      }
    }
 
    // Taking final thread-specific time measurement
    _threadStepTime[threadId] = jaffarCommon::timing::timeDeltaMicroseconds(jaffarCommon::timing::now(), threadTime0);
  }
 
  __INLINE__ inputResult_t runNewInput(Runner& r, const void* baseStateData, const InputSet::inputIndex_t input, threadAccumulator_t& acc, const size_t threadId)
  {
    // Increasing new state counter
    acc.newStatesProcessed++;
 
    // Re-loading base state (slab slot: hot slot + cold path)
    JAFFAR_PROF_DECL(t0);
    _stateDb->loadStateFromSlot(r, baseStateData);
    r.setSearchStep(_currentStep); // base state's depth = current search step (count is not stored per-state)
    JAFFAR_PROF_ACC(acc.runnerStateLoad, t0);
 
    // Running input
    const auto result = runInput(r, input, acc, threadId);
 
    // Update counters depending on the outcomes
    if (result == inputResult_t::normal) acc.normalStates++;
    if (result == inputResult_t::repeated) acc.repeatedStates++;
    if (result == inputResult_t::failed) acc.failedStates++;
    if (result == inputResult_t::win) acc.winStates++;
    if (result == inputResult_t::droppedNoStorage) acc.droppedStatesNoStorage++;
    if (result == inputResult_t::droppedFailedSerialization) acc.droppedStatesFailedSerialization++;
    if (result == inputResult_t::droppedCheckpoint) acc.droppedStatesCheckpoint++;
 
    // Checking whether this state's checkpoint is new
    const auto stateCheckpointLevel     = r.getGame()->getCheckpointLevel();
    const auto stateCheckpointTolerance = r.getGame()->getCheckpointTolerance();
    if (stateCheckpointLevel > _checkpointLevel)
    {
      _checkpointLevel     = stateCheckpointLevel;
      _checkpointTolerance = stateCheckpointTolerance;
      _checkpointCutoff    = _currentStep + stateCheckpointTolerance;
    }
 
    // Returning result
    return result;
  }
 
  __INLINE__ inputResult_t runInput(Runner& r, const InputSet::inputIndex_t input, threadAccumulator_t& acc, const size_t threadId)
  {
    // Now advancing state with the provided input
    JAFFAR_PROF_DECL(t1);
    r.advanceState(input);
    JAFFAR_PROF_ACC(acc.runnerStateAdvance, t1);
 
    // Computing runner hash
    JAFFAR_PROF_DECL(t2);
    const auto hash = r.computeHash();
    JAFFAR_PROF_ACC(acc.calculateHash, t2);
 
    // Checking if hash is repeated (i.e., has been seen before)
    JAFFAR_PROF_DECL(t3);
    bool hashExists = _hashDbEnabled ? _hashDb->checkHashExists(hash) : false;
    JAFFAR_PROF_ACC(acc.checkHash, t3);
 
    // If state is repeated then we are not interested in it, continue
    if (hashExists == true) return inputResult_t::repeated;
 
    // Evaluating game rules based on the new state
    JAFFAR_PROF_DECL(t4);
    r.getGame()->evaluateRules();
 
    // Checking whether this state meets checkpoint
    if (_currentStep > _checkpointCutoff)
    {
      const auto stateCheckpointLevel = r.getGame()->getCheckpointLevel();
 
      // If state does not meet checkpoint, then do not process it further
      if (stateCheckpointLevel < _checkpointLevel) return inputResult_t::droppedCheckpoint;
    }
 
    // Determining state type
    r.getGame()->updateGameStateType();
 
    // Getting state type
    const auto stateType = r.getGame()->getStateType();
    JAFFAR_PROF_ACC(acc.ruleChecking, t4);
 
    // Now we have determined the state is not repeated, check if it's not a failed state
    if (stateType == Game::stateType_t::fail) return inputResult_t::failed;
 
    // Now that the state is not failed nor repeated, this is effectively a new state to add
    JAFFAR_PROF_DECL(t5);
    void* newStateData = _stateDb->getFreeState(threadId);
    JAFFAR_PROF_ACC(acc.getFreeState, t5);
 
    // If couldn't get any memory, simply drop the state
    if (newStateData == nullptr) return inputResult_t::droppedNoStorage;
 
    // Updating state reward
    JAFFAR_PROF_DECL(t6);
    r.getGame()->updateReward();
 
    // Getting state reward
    const auto reward = r.getGame()->getReward();
    JAFFAR_PROF_ACC(acc.calculateReward, t6);
 
    // If this is a win state, register it and return
    if (stateType == Game::stateType_t::win)
    {
 
      // Check if the new win state is the best and store it in that case
      _stepBestWinStateLock.lock();
      if (reward > _stepBestWinState.reward)
      {
        _stateDb->saveStateFromRunner(r, _stepBestWinState.stateData);
        _stepBestWinState.reward    = reward;
        _stepBestWinState.stepCount = r.getStepCount(); // record depth: the count is not serialized per-state
      }
      _stepBestWinStateLock.unlock();
 
      // Freeing up the state data
      JAFFAR_PROF_DECL(t7);
      _stateDb->returnFreeState(newStateData, threadId);
      JAFFAR_PROF_ACC(acc.returnFreeState, t7);
 
      // Returning a win result
      return inputResult_t::win;
    }
 
    // If this is a normal state and has possible inputs store it in the next state database
    if (stateType == Game::stateType_t::normal)
    {
      // If this is a normal state, push into the state database
      JAFFAR_PROF_DECL(t8);
      auto success = _stateDb->pushState(reward, r, newStateData);
      JAFFAR_PROF_ACC(acc.runnerStateSave, t8);
 
      // If pushing the state failed (e.g. serialization error), drop it and continue, keeping a counter
      if (success == false)
      {
        // Freeing up state memory
        JAFFAR_PROF_DECL(t9);
        _stateDb->returnFreeState(newStateData, threadId);
        JAFFAR_PROF_ACC(acc.returnFreeState, t9);
 
        // Returning dropped result by failed serialization
        return inputResult_t::droppedFailedSerialization;
      }
    }
 
    // Checking for manual saved solution is required
    const auto currentLastRuleIdx = r.getGame()->getSaveSolutionCurrentLastRuleIdx();
    if (r.getGame()->isSaveSolution() && currentLastRuleIdx > _manualSaveSolutionActiveLastRuleId)
    {
      // Grab lock
      _manualSaveSolutionLock.lock();
 
      // Do this only if reward is better
      if (reward > _manualSaveSolution.reward)
      {
        // Store path, data, and reward
        _stateDb->saveStateFromRunner(r, _manualSaveSolution.stateData);
        _manualSaveSolution.path             = r.getGame()->getSaveSolutionPath();
        _manualSaveSolution.reward           = reward;
        _manualSaveSolution.lastRuleIdx      = currentLastRuleIdx;
        _manualSaveSolution.stepCount        = r.getStepCount(); // record depth (the count is not serialized per-state)
        _manualSaveSolutionUpdatedLastRuleId = true;
      }
 
      // Release lock
      _manualSaveSolutionLock.unlock();
    }
 
    // If store succeeded, return a normal execution
    return inputResult_t::normal;
  }
 
  jaffarCommon::concurrent::HashMap_t<jaffarCommon::hash::hash_t, jaffarCommon::concurrent::HashSet_t<InputSet::inputIndex_t>> _candidateInputsDetected;
 
  size_t _currentStep = 0;
 
  std::vector<std::unique_ptr<Runner>> _runners;
 
  std::unique_ptr<jaffarPlus::StateDb> _stateDb;
 
  std::shared_ptr<void> _inputHistoryBacking;
 
  bool   _hashDbEnabled;
  size_t _baseStateBatch; 
 
  std::unique_ptr<jaffarPlus::HashDb> _hashDb;
 
  size_t _stateSizeInDatabase;
 
  size_t _fullStateSize;
 
  std::mutex  _stepBestWinStateLock; 
  stateInfo_t _stepBestWinState;     
 
  // Storage for manually triggered save solutionm
 
  std::mutex           _manualSaveSolutionLock;              
  manualSaveSolution_t _manualSaveSolution;                  
  bool                 _manualSaveSolutionUpdatedLastRuleId; 
  ssize_t              _manualSaveSolutionActiveLastRuleId;  
  std::string          _manualSaveSolutionLastPath = "";     
 
  // Checkpoint information
  size_t _checkpointLevel;     
  size_t _checkpointTolerance; 
  size_t _checkpointCutoff;    
 
 
  std::atomic<size_t> _droppedStatesNoStorage;
 
  std::atomic<size_t> _droppedStatesFailedSerialization;
 
  std::atomic<size_t> _droppedStatesCheckpoint;
 
  std::atomic<size_t> _repeatedStates;
 
  std::atomic<size_t> _failedStates;
 
  std::atomic<size_t> _winStates;
 
  std::atomic<size_t> _normalStates;
 
  std::atomic<size_t> _stepBaseStatesProcessed;  
  std::atomic<size_t> _totalBaseStatesProcessed; 
 
  std::atomic<size_t> _stepNewStatesProcessed;  
  std::atomic<size_t> _totalNewStatesProcessed; 
 
 
  size_t _currentStepTime;
 
  std::vector<size_t> _threadStepTime;            
  size_t              _maxThreadStepTime;         
  size_t              _maxThreadStepTimeThreadId; 
 
  std::vector<threadAccumulator_t> _threadAccumulators;
 
  size_t _totalRunningTime;
 
  // Time spent advancing runner state per step
  std::atomic<size_t> _runnerStateAdvanceThreadRawTime;         
  std::atomic<size_t> _runnerStateAdvanceAverageTime;           
  std::atomic<size_t> _runnerStateAdvanceAverageCumulativeTime; 
 
  // Time spent loading states into the runner
  std::atomic<size_t> _runnerStateLoadThreadRawTime;         
  std::atomic<size_t> _runnerStateLoadAverageTime;           
  std::atomic<size_t> _runnerStateLoadAverageCumulativeTime; 
 
  // Time spent saving runner states into the state db
  std::atomic<size_t> _runnerStateSaveThreadRawTime;         
  std::atomic<size_t> _runnerStateSaveAverageTime;           
  std::atomic<size_t> _runnerStateSaveAverageCumulativeTime; 
 
  // Time spent calculating hash
  std::atomic<size_t> _calculateHashThreadRawTime;         
  std::atomic<size_t> _calculateHashAverageTime;           
  std::atomic<size_t> _calculateHashAverageCumulativeTime; 
 
  // Time spent checking hash
  std::atomic<size_t> _checkHashThreadRawTime;         
  std::atomic<size_t> _checkHashAverageTime;           
  std::atomic<size_t> _checkHashAverageCumulativeTime; 
 
  // Rule checking time
  std::atomic<size_t> _ruleCheckingThreadRawTime;         
  std::atomic<size_t> _ruleCheckingAverageTime;           
  std::atomic<size_t> _ruleCheckingAverageCumulativeTime; 
 
  // Get free state time
  std::atomic<size_t> _getFreeStateThreadRawTime;         
  std::atomic<size_t> _getFreeStateAverageTime;           
  std::atomic<size_t> _getFreeStateAverageCumulativeTime; 
 
  // Return free state time
  std::atomic<size_t> _returnFreeStateThreadRawTime;         
  std::atomic<size_t> _returnFreeStateAverageTime;           
  std::atomic<size_t> _returnFreeStateAverageCumulativeTime; 
 
  // Reward calculation time
  std::atomic<size_t> _calculateRewardThreadRawTime;         
  std::atomic<size_t> _calculateRewardAverageTime;           
  std::atomic<size_t> _calculateRewardAverageCumulativeTime; 
 
  // Get allowed inputs time
  std::atomic<size_t> _getAllowedInputsThreadRawTime;         
  std::atomic<size_t> _getAllowedInputsAverageTime;           
  std::atomic<size_t> _getAllowedInputsAverageCumulativeTime; 
 
  // Get candidate inputs time
  std::atomic<size_t> _getCandidateInputsThreadRawTime;         
  std::atomic<size_t> _getCandidateInputsAverageTime;           
  std::atomic<size_t> _getCandidateInputsAverageCumulativeTime; 
 
  // Advance Hash DB time
  std::atomic<size_t> _advanceHashDbThreadRawTime;         
  std::atomic<size_t> _advanceHashDbAverageTime;           
  std::atomic<size_t> _advanceHashDbAverageCumulativeTime; 
 
  // Advance State DB time
  std::atomic<size_t> _advanceStateDbThreadRawTime;         
  std::atomic<size_t> _advanceStateDbAverageTime;           
  std::atomic<size_t> _advanceStateDbAverageCumulativeTime; 
 
  // Popping states from the State DB time
  std::atomic<size_t> _popBaseStateDbThreadRawTime;         
  std::atomic<size_t> _popBaseStateDbAverageTime;           
  std::atomic<size_t> _popBaseStateDbAverageCumulativeTime; 
 
  size_t _subTotalAverageTime;           
  size_t _subTotalAverageCumulativeTime; 
};
 
} // namespace jaffarPlus