include/anna/statistics/Engine.hpp

   1 // ANNA - Anna is Not Nothingness Anymore                                                         //
   2 //                                                                                                //
   3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
   4 //                                                                                                //
   5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
   6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
   7
   8
   9 #ifndef anna_statistics_Engine_hpp
  10 #define anna_statistics_Engine_hpp
  11
  12 #include <anna/core/Singleton.hpp>
  13 #include <anna/core/util/Millisecond.hpp>
  14 #include <anna/core/mt/Mutex.hpp>
  15
  16 // Standard
  17 #include <string>
  18 #include <vector>
  19 #include <map>
  20
  21 // Local
  22 #include <anna/statistics/Accumulator.hpp>
  23
  24 namespace anna {
  25 namespace xml {
  26 class Node;
  27 }
  28 }
  29
  30
  31
  32 namespace anna {
  33
  34 namespace statistics {
  35
  36
  37 typedef struct {
  38
  39   std::string SampleFile; // Sample file to optional writtings
  40   std::string Description;
  41   std::string Unit;
  42   bool IntegerNatureSample;
  43
  44 } _concept_identification_t;
  45
  46 typedef std::map <int, _concept_identification_t> _concept_identification_map_t;
  47 typedef std::map <int, _concept_identification_t>::const_iterator _concept_identification_map_iter;
  48 typedef std::map <int, _concept_identification_t>::iterator _concept_identification_map_nc_iter;
  49
  50 typedef std::vector <Accumulator*> _accumulator_vector_t;
  51 typedef std::vector <Accumulator*>::const_iterator _accumulator_vector_it;
  52
  53
  54 /**
  55 * Class used to configure general behaviour of statistics processing
  56 * By default, the engine is disabled and #enable must be invoked
  57 */
  58
  59 class Engine : public anna::Singleton <Engine> {
  60
  61
  62 public:
  63
  64   /** Destructor */
  65   ~Engine();
  66
  67   // Sets
  68
  69   /**
  70   * Adds a new statistic concept (for example "Time_between_processA_and_processB", "Database time", etc)
  71   *
  72   * @param description Concept description
  73   * @param unit Concept unit description
  74   * @param integerNatureSample Most of cases we will measure 'time' with the unit which force integer values
  75   *                            (is more intuitive 850 msecs than 0,850 secs). Then, it is @em true by default.
  76   *                            This is useful to advice better representation for some indicators like minimum/maximum
  77   *                             within integer samples.
  78   *
  79   * @return Assigned concept identification number (sequence)
  80   */
  81   int addConcept(const std::string & description, const std::string & unit, const bool & integerNatureSample = true) throw();
  82
  83
  84   /**
  85   * Stops statistics engine
  86   */
  87   void enable(void) throw() { a_enabled = true; }
  88
  89
  90   /**
  91   * Starts statistics engine
  92   */
  93   void disable(void) throw() { a_enabled = false; }
  94
  95   /**
  96   * Enable sample log for statistics processings. Engine starts with this feature disabled. When a new concept id is added
  97   * to the engine, sample log is also disabled for it.
  98   *
  99   * Sample logs are used to dump each processing for a certain concept identification (<unix timestamp>,<processed value>).
 100   *
 101   *
 102   * @param id Concept identification. If -1 value is provided, all concepts will be activated.
 103   * @param sampleFileName Absolute or relative to execution path, and completed with extension '.<concept id>.csv'. Empty string, disables log. Default file name is 'sample'
 104   *
 105   * @return @em false if not concept is registered with provided id
 106   * @warning Many systems add concepts dynamically. This method only affects to current concepts registered at statistics engine.
 107   */
 108   bool enableSampleLog(const int & id = -1, const char *sampleFileName = NULL) throw();
 109
 110
 111   /**
 112   * Disable sample log for statistics processings
 113   *
 114   * @param id Concept identification.
 115   *
 116   * @return @em false if not concept is registered with provided id
 117   */
 118   bool disableSampleLog(const int & id) throw();
 119
 120   // Gets
 121
 122   /**
 123   * Gets statistic concept information.
 124   *
 125   * @param id Concept identification.
 126   * @param description Concept description returned by reference
 127   * @param unit Concept unit description returned by reference
 128   * @param integerNatureSample nature returned by reference
 129   *
 130   * @return @em false if not concept is registered with provided id
 131   */
 132   bool getConcept(const int & id, std::string & description, std::string & unit, bool & integerNatureSample) const throw();
 133
 134
 135   /**
 136   * Boolean about engine state (enabled / disabled)
 137   */
 138   bool enabled(void) const throw() { return (a_enabled); }
 139
 140   /**
 141   * There is an advantage creating Accumulators over the engine: the #asXML method will show all the controlled information
 142   * easily. Anyway, you could allocate this class objects without using this. Then, this is a helper to create accumulators
 143   * and centralize their reports.
 144   *
 145   * @param name Accumulator name
 146   *
 147   * @return New allocated accumulator, to be used by the client
 148   */
 149   Accumulator *createAccumulator(const std::string &name) throw();
 150
 151   /**
 152   * Class string representation
 153   *
 154   * @return String with class content
 155   */
 156   std::string asString(void) const throw();
 157
 158
 159   /**
 160   * Class XML representation
 161   *
 162   * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
 163   *
 164   * @return XML with class content
 165   */
 166   anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const throw();
 167
 168
 169 private:
 170
 171   Engine(); // private constructor
 172
 173   _concept_identification_map_t a_concept_identification_map;
 174   _accumulator_vector_t a_accumulators; // you could create accumulators regardless the engine, but this is easier and asXML will show all the information easily
 175   bool a_enabled;
 176   int a_sequence_concept_id;
 177   anna::Mutex a_mutex; // for logSample
 178
 179   bool logSample(const int & conceptId, const anna::Millisecond & unixTimestamp, const double & value) const throw();
 180
 181   friend class anna::Singleton <Engine>;
 182   friend class Accumulator;
 183 };
 184
 185
 186 }
 187 }
 188
 189 #endif