Code/CryPlugins/CryUQS/Core/core/QueryBase.h

   1 // Copyright 2001-2018 Crytek GmbH / Crytek Group. All rights reserved.
   2
   3 #pragma once
   4
   5 // *INDENT-OFF* - <hard to read code and declarations due to inconsistent indentation>
   6
   7 namespace UQS
   8 {
   9         namespace Core
  10         {
  11
  12                 class CHistoricQuery;
  13
  14                 //===================================================================================
  15                 //
  16                 // HistoricQuerySharedPtr
  17                 //
  18                 //===================================================================================
  19
  20                 // FIXME: shouldn't be here (a better place would be QueryHistory.h since it defines CHistoricQuery), but some #include dependencies are currently enforcing us to do it this way
  21                 typedef std::shared_ptr<CHistoricQuery> HistoricQuerySharedPtr;
  22
  23                 //===================================================================================
  24                 //
  25                 // CQueryBase
  26                 //
  27                 // - base class for all query classes
  28                 // - the actual classes will get instantiated from a CQueryBlueprint at game runtime through their query factories
  29                 //
  30                 //===================================================================================
  31
  32                 class CQueryBlueprint;
  33
  34                 class CQueryBase
  35                 {
  36                 public:
  37
  38                         //===================================================================================
  39                         //
  40                         // SCtorContext
  41                         //
  42                         //===================================================================================
  43
  44                         struct SCtorContext
  45                         {
  46                                 explicit                                SCtorContext(const CQueryID& _queryID, const char* _szQuerierName, const HistoricQuerySharedPtr& _pOptionalHistoryToWriteTo, const std::shared_ptr<CItemList>& _pOptionalResultingItemsFromPreviousQuery);
  47
  48                                 CQueryID                                queryID;
  49                                 const char*                             szQuerierName;
  50                                 HistoricQuerySharedPtr                  pOptionalHistoryToWriteTo;
  51                                 std::shared_ptr<CItemList>              pOptionalResultingItemsFromPreviousQuery;     // this is how we pass items of a result set from one query to another
  52                         };
  53
  54                         //===================================================================================
  55                         //
  56                         // EUpdateState
  57                         //
  58                         //===================================================================================
  59
  60                         enum class EUpdateState
  61                         {
  62                                 StillRunning,                           // the query is still running
  63                                 Finished,                               // the query has finished without errors
  64                                 ExceptionOccurred                       // an error occurred while the query was running; an error message that was passed to Update() then contains some details
  65                         };
  66
  67                         //===================================================================================
  68                         //
  69                         // SGrantedAndUsedTime
  70                         //
  71                         // - for detailed per-frame statistics of how much time was granted and how much time was actually used to do some work
  72                         //
  73                         //===================================================================================
  74
  75                         struct SGrantedAndUsedTime
  76                         {
  77                                 explicit                                SGrantedAndUsedTime();
  78                                 explicit                                SGrantedAndUsedTime(const CTimeValue& _granted, const CTimeValue& _used);
  79                                 void                                    Serialize(Serialization::IArchive& ar);
  80
  81                                 CTimeValue                              granted;
  82                                 CTimeValue                              used;
  83                         };
  84
  85                         //===================================================================================
  86                         //
  87                         // SStatistics
  88                         //
  89                         // - overall statistics of the query
  90                         // - can be retrieved at any time even while the query is still running to get some "live insight" into what's going on
  91                         //
  92                         //===================================================================================
  93
  94                         struct SStatistics
  95                         {
  96                                 explicit                                SStatistics();
  97                                 void                                    Serialize(Serialization::IArchive& ar);
  98
  99                                 // known to + set by CQueryBase (common stuff used by all query types)
 100                                 // this is stuff that CQueryManager::DebugDrawQueryStatistics() is partly interested in (but it's also interested in the number of items - hmmm, could we just display the elapsed frames instead?)
 101                                 string                                  querierName;
 102                                 string                                  queryBlueprintName;
 103                                 size_t                                  queryCreatedFrame;
 104                                 CTimeValue                              queryCreatedTimestamp;
 105                                 size_t                                  totalConsumedFrames;
 106                                 CTimeValue                              totalConsumedTime;
 107                                 std::vector<SGrantedAndUsedTime>        grantedAndUsedTimePerFrame;       // grows with each update call
 108
 109                                 // could be known to composite query classes that pass around the resulting items (but currently only known to + set by CQuery_Regular)
 110                                 size_t                                  numDesiredItems;                  // number of items the user wants to find; this is often 1 (e. g. "give me *one* good shooting position"), but can be any number, whereas 0 has a special meaning: "give me all items you can find"
 111                                 size_t                                  numGeneratedItems;                // number of items the generator has produced
 112                                 size_t                                  numRemainingItemsToInspect;       // this number decreases with each finished item while the query is ongoing
 113                                 size_t                                  numItemsInFinalResultSet;         // number of items that finally made it into the result set
 114                                 size_t                                  memoryUsedByGeneratedItems;       // amount of memory used by all generated items; this memory is usually used on the client side (since they provide us with an item generator that we just call)
 115                                 size_t                                  memoryUsedByItemsWorkingData;     // amount of memory used to keep track of the working state of all items throughout the evaluation phases
 116
 117                                 // known to + set by CQuery_Regular only (as it deals with several phases which is specific for that class)
 118                                 std::vector<size_t>                     elapsedFramesPerPhase;
 119                                 std::vector<CTimeValue>                 elapsedTimePerPhase;
 120                                 std::vector<CTimeValue>                 peakElapsedTimePerPhaseUpdate;
 121                                 std::vector<size_t>                     instantEvaluatorsRuns;            // how often has each kind of instant-evaluator been run
 122                                 std::vector<size_t>                     deferredEvaluatorsFullRuns;       // how often has each kind of deferred-evaluator been fully run (i. e. started and run until it completed all work an a given item)
 123                                 std::vector<size_t>                     deferredEvaluatorsAbortedRuns;    // how often has each kind of deferred-evaluator been been started, but got prematurely aborted as the item was being discarded in the meantime
 124                         };
 125
 126                 public:
 127                         explicit                                    CQueryBase(const SCtorContext& ctorContext, bool bRequiresSomeTimeBudgetForExecution);
 128                         virtual                                     ~CQueryBase();
 129
 130                         bool                                        RequiresSomeTimeBudgetForExecution() const;
 131                         bool                                        InstantiateFromQueryBlueprint(const std::shared_ptr<const CQueryBlueprint>& pQueryBlueprint, const Shared::IVariantDict& runtimeParams, Shared::CUqsString& error);
 132                         void                                        AddItemMonitor(Client::ItemMonitorUniquePtr&& pItemMonitor);
 133                         void                                        TransferAllItemMonitorsToOtherQuery(CQueryBase& receiver);
 134                         EUpdateState                                Update(const CTimeValue& amountOfGrantedTime, Shared::CUqsString& error);
 135                         void                                        Cancel();
 136                         void                                        GetStatistics(SStatistics& out) const;
 137
 138                         // careful: using the result while the query is still in EUpdateState::StillRunning state is undefined behavior
 139                         QueryResultSetUniquePtr                     ClaimResultSet();
 140
 141                         // debugging
 142                         const char*                                 GetQuerierName() const;
 143                         HistoricQuerySharedPtr                      GetHistoricQuery() const;   // might return a nullptr if history logging was not enabled
 144
 145                 private:
 146                         virtual bool                                OnInstantiateFromQueryBlueprint(const Shared::IVariantDict& runtimeParams, Shared::CUqsString& error) = 0;
 147                         virtual EUpdateState                        OnUpdate(Shared::CUqsString& error) = 0;
 148                         virtual void                                OnCancel() = 0;
 149                         virtual void                                OnGetStatistics(SStatistics& out) const = 0;
 150
 151                         void                                        AddItemsFromGlobalParametersToDebugRenderWorld() const;
 152
 153                 protected:
 154                         // debugging
 155                         string                                      m_querierName;                    // debug name that the caller passed in to re-identify his query for debugging purposes
 156                         HistoricQuerySharedPtr                      m_pHistory;                       // optional; used to build a history of the ongoing query (and to pass its debug-renderworld to all evaluators)
 157                         // ~debugging
 158
 159                         const CQueryID                              m_queryID;                        // the unique queryID that can be used to identify this instance from inside the CQueryManager
 160                         std::shared_ptr<const CQueryBlueprint>      m_pQueryBlueprint;                // we'll instantiate all query components (generator, evaluators, etc) via this blueprint
 161                         std::shared_ptr<CItemList>                  m_pOptionalShuttledItems;         // when queries are chained, the items in the result set of the previous query will be transferred to here (ready to get evaluated straight away)
 162                         QueryResultSetUniquePtr                     m_pResultSet;                     // once the query has finished evaluating all items (and hasn't bumped into a runtime exception), it will write the final items to here
 163                         CTimeBudget                                 m_timeBudgetForCurrentUpdate;     // this gets "restarted" on each Update() call with the amount of granted time that has been passed in by the caller
 164
 165                 private:
 166                         // debugging
 167                         CTimeValue                                  m_queryCreatedTimestamp;          // timestamp of when the query was created (via its ctor)
 168                         size_t                                      m_queryCreatedFrame;              // system frame number in which the query was created (via its ctor)
 169                         size_t                                      m_totalConsumedFrames;            // runaway-counter that increments on each Update() call
 170                         CTimeValue                                  m_totalConsumedTime;              // run-away timer that increments on each Update() call
 171                         std::vector<SGrantedAndUsedTime>            m_grantedAndUsedTimePerFrame;     // keeps track of how much time we were given to do some work on each frame and how much time we actually spent; grows on each Update() call
 172                         // ~debugging
 173
 174                         const bool                                  m_bRequiresSomeTimeBudgetForExecution;
 175                         Shared::CVariantDict                        m_globalParams;                   // merge between constant- and runtime-params
 176                         std::vector<Client::ItemMonitorUniquePtr>   m_itemMonitors;                   // Update() checks these to ensure that no corruption of the reasoning space goes unnoticed; when the query finishes, these monitors may get transferred to the parent to carry on monitoring alongside further child queries
 177
 178                 protected:
 179                         // !! m_blackboard: this needs to come after all other member variables, as it relies on their proper initialization!!
 180                         SQueryBlackboard                            m_blackboard;                     // bundles some stuff for functions, generators and evaluators to read from it
 181
 182                 private:
 183                         static const CDebugRenderWorldImmediate     s_debugRenderWorldImmediate;      // handed out to all generators, evaluators and functions if immediate debug-rendering is turned on via SCvars::debugDraw
 184                 };
 185
 186         }
 187 }