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) ;
  86
  87
  88   /**
  89   * Stops statistics engine
  90   */
  91   void enable(void) { a_enabled = true; }
  92
  93
  94   /**
  95   * Starts statistics engine
  96   */
  97   void disable(void) { 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) ;
 113
 114
 115   /**
 116   * Disable sample log for statistics processings
 117   *
 118   * @param id Concept identification. If -1 value is provided, all concepts will be deactivated.
 119   *
 120   * @return @em false if not concept is registered with provided id
 121   * @warning Many systems add concepts dynamically. This method only affects to current concepts registered at statistics engine.
 122   */
 123   bool disableSampleLog(const int & id = -1) ;
 124
 125   // Gets
 126
 127   /**
 128   * Gets statistic concept information.
 129   *
 130   * @param id Concept identification.
 131   * @param description Concept description returned by reference
 132   * @param unit Concept unit description returned by reference
 133   * @param integerNatureSample nature returned by reference
 134   *
 135   * @return @em false if not concept is registered with provided id
 136   */
 137   bool getConcept(const int & id, std::string & description, std::string & unit, bool & integerNatureSample) const ;
 138
 139
 140   /**
 141   * Boolean about engine state (enabled / disabled)
 142   */
 143   bool enabled(void) const { return (a_enabled); }
 144
 145
 146   /**
 147    * Creates a statistic accumulator
 148    *
 149    * @param name Accumulator name
 150    *
 151    * \return The accumulator created or exception when already exists for the provided name.
 152    */
 153   Accumulator *createAccumulator(const std::string &name) noexcept(false);
 154
 155   /**
 156    * Returns accumulator instance identified by name.
 157    *
 158    * \param name Accumulator name
 159    *
 160    * \return The accumulator instance identified by name provided, NULL if not found
 161    */
 162   Accumulator* getAccumulator(const std::string &name) ;
 163
 164
 165
 166   /**
 167   * Class string representation
 168   *
 169   * @return String with class content
 170   */
 171   std::string asString(void) const ;
 172
 173
 174   /**
 175   * Class XML representation
 176   *
 177   * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
 178   *
 179   * @return XML with class content
 180   */
 181   anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const ;
 182
 183
 184 private:
 185
 186   Engine(); // private constructor
 187
 188   _concept_identification_map_t a_concept_identification_map;
 189   _accumulator_map_t a_accumulators; // you could create accumulators regardless the engine, but this is easier and asXML will show all the information easily
 190   bool a_enabled;
 191   int a_sequence_concept_id;
 192   anna::Mutex a_mutex; // for logSample
 193
 194   bool logSample(const int & conceptId, const anna::Millisecond & unixTimestamp, const double & value) const ;
 195
 196   friend class anna::Singleton <Engine>;
 197   friend class Accumulator;
 198 };
 199
 200
 201 }
 202 }
 203
 204 #endif