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/RuntimeException.hpp>
  15 #include <anna/core/mt/Mutex.hpp>
  16
  17 // Standard
  18 #include <string>
  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 class Accumulator;
  38
  39
  40 typedef struct {
  41
  42   std::string SampleFile; // Sample file to optional writtings
  43   std::string Description;
  44   std::string Unit;
  45   bool IntegerNatureSample;
  46
  47 } _concept_identification_t;
  48
  49 typedef std::map <int, _concept_identification_t> _concept_identification_map_t;
  50 typedef std::map <int, _concept_identification_t>::const_iterator _concept_identification_map_iter;
  51 typedef std::map <int, _concept_identification_t>::iterator _concept_identification_map_nc_iter;
  52
  53 typedef std::map <std::string, Accumulator*> _accumulator_map_t;
  54 typedef std::map <std::string, Accumulator*>::const_iterator _accumulator_map_it;
  55 typedef std::map <std::string, Accumulator*>::iterator _accumulator_map_nc_it;
  56
  57
  58 /**
  59 * Class used to configure general behaviour of statistics processing
  60 * By default, the engine is disabled and #enable must be invoked
  61 */
  62
  63 class Engine : public anna::Singleton <Engine> {
  64
  65
  66 public:
  67
  68   /** Destructor */
  69   ~Engine();
  70
  71   // Sets
  72
  73   /**
  74   * Adds a new statistic concept (for example "Time_between_processA_and_processB", "Database time", etc)
  75   *
  76   * @param description Concept description
  77   * @param unit Concept unit description
  78   * @param integerNatureSample Most of cases we will measure 'time' with the unit which force integer values
  79   *                            (is more intuitive 850 msecs than 0,850 secs). Then, it is @em true by default.
  80   *                            This is useful to advice better representation for some indicators like minimum/maximum
  81   *                             within integer samples.
  82   *
  83   * @return Assigned concept identification number (sequence)
  84   */
  85   int addConcept(const std::string & description, const std::string & unit, const bool & integerNatureSample = true) throw();
  86
  87
  88   /**
  89   * Stops statistics engine
  90   */
  91   void enable(void) throw() { a_enabled = true; }
  92
  93
  94   /**
  95   * Starts statistics engine
  96   */
  97   void disable(void) throw() { a_enabled = false; }
  98
  99   /**
 100   * Enable sample log for statistics processings. Engine starts with this feature disabled. When a new concept id is added
 101   * to the engine, sample log is also disabled for it.
 102   *
 103   * Sample logs are used to dump each processing for a certain concept identification (<unix timestamp>,<processed value>).
 104   *
 105   *
 106   * @param id Concept identification. If -1 value is provided, all concepts will be activated.
 107   * @param sampleFileName Absolute or relative to execution path, and completed with extension '.<concept id>.csv'. Empty string, disables log. Default file name is 'sample'
 108   *
 109   * @return @em false if not concept is registered with provided id
 110   * @warning Many systems add concepts dynamically. This method only affects to current concepts registered at statistics engine.
 111   */
 112   bool enableSampleLog(const int & id = -1, const char *sampleFileName = NULL) throw();
 113
 114
 115   /**
 116   * Disable sample log for statistics processings
 117   *
 118   * @param id Concept identification.
 119   *
 120   * @return @em false if not concept is registered with provided id
 121   */
 122   bool disableSampleLog(const int & id) throw();
 123
 124   // Gets
 125
 126   /**
 127   * Gets statistic concept information.
 128   *
 129   * @param id Concept identification.
 130   * @param description Concept description returned by reference
 131   * @param unit Concept unit description returned by reference
 132   * @param integerNatureSample nature returned by reference
 133   *
 134   * @return @em false if not concept is registered with provided id
 135   */
 136   bool getConcept(const int & id, std::string & description, std::string & unit, bool & integerNatureSample) const throw();
 137
 138
 139   /**
 140   * Boolean about engine state (enabled / disabled)
 141   */
 142   bool enabled(void) const throw() { return (a_enabled); }
 143
 144
 145   /**
 146    * Creates a statistic accumulator
 147    *
 148    * @param name Accumulator name
 149    *
 150    * \return The accumulator created or exception when already exists for the provided name.
 151    */
 152   Accumulator *createAccumulator(const std::string &name) throw(anna::RuntimeException);
 153
 154   /**
 155    * Returns accumulator instance identified by name.
 156    *
 157    * \param name Accumulator name
 158    *
 159    * \return The accumulator instance identified by name provided, NULL if not found
 160    */
 161   Accumulator* getAccumulator(const std::string &name) throw();
 162
 163
 164
 165   /**
 166   * Class string representation
 167   *
 168   * @return String with class content
 169   */
 170   std::string asString(void) const throw();
 171
 172
 173   /**
 174   * Class XML representation
 175   *
 176   * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
 177   *
 178   * @return XML with class content
 179   */
 180   anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const throw();
 181
 182
 183 private:
 184
 185   Engine(); // private constructor
 186
 187   _concept_identification_map_t a_concept_identification_map;
 188   _accumulator_map_t a_accumulators; // you could create accumulators regardless the engine, but this is easier and asXML will show all the information easily
 189   bool a_enabled;
 190   int a_sequence_concept_id;
 191   anna::Mutex a_mutex; // for logSample
 192
 193   bool logSample(const int & conceptId, const anna::Millisecond & unixTimestamp, const double & value) const throw();
 194
 195   friend class anna::Singleton <Engine>;
 196   friend class Accumulator;
 197 };
 198
 199
 200 }
 201 }
 202
 203 #endif