include/anna/statistics/Engine.hpp

   1 // ANNA - Anna is Not 'N' Anymore
   2 //
   3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
   4 //
   5 // https://bitbucket.org/testillano/anna
   6 //
   7 // Redistribution and use in source and binary forms, with or without
   8 // modification, are permitted provided that the following conditions
   9 // are met:
  10 //
  11 //     * Redistributions of source code must retain the above copyright
  12 // notice, this list of conditions and the following disclaimer.
  13 //     * Redistributions in binary form must reproduce the above
  14 // copyright notice, this list of conditions and the following disclaimer
  15 // in the documentation and/or other materials provided with the
  16 // distribution.
  17 //     * Neither the name of Google Inc. nor the names of its
  18 // contributors may be used to endorse or promote products derived from
  19 // this software without specific prior written permission.
  20 //
  21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 //
  33 // Authors: eduardo.ramos.testillano@gmail.com
  34 //          cisco.tierra@gmail.com
  35
  36
  37 #ifndef anna_statistics_Engine_hpp
  38 #define anna_statistics_Engine_hpp
  39
  40 #include <anna/core/Singleton.hpp>
  41 #include <anna/core/util/Millisecond.hpp>
  42
  43 // Standard
  44 #include <string>
  45 #include <map>
  46
  47 // Local
  48 #include <anna/statistics/Accumulator.hpp>
  49
  50 namespace anna {
  51 namespace xml {
  52 class Node;
  53 }
  54 }
  55
  56
  57
  58 namespace anna {
  59
  60 namespace statistics {
  61
  62
  63 typedef struct {
  64
  65   std::string SampleFile; // Sample file to optional writtings
  66   std::string Description;
  67   std::string Unit;
  68   bool IntegerNatureSample;
  69
  70 } _concept_identification_t;
  71
  72 typedef std::map <int, _concept_identification_t> _concept_identification_map_t;
  73 typedef std::map <int, _concept_identification_t>::const_iterator _concept_identification_map_iter;
  74 typedef std::map <int, _concept_identification_t>::iterator _concept_identification_map_nc_iter;
  75
  76
  77
  78 /**
  79 * Class used to configure general behaviour of statistics processing
  80 * By default, the engine is disabled and #enable must be invoked
  81 */
  82
  83 class Engine : public anna::Singleton <Engine> {
  84
  85
  86 public:
  87
  88   // Sets
  89
  90   /**
  91   * Adds a new statistic concept (for example "Time_between_processA_and_processB", "Database time", etc)
  92   *
  93   * @param description Concept description
  94   * @param unit Concept unit description
  95   * @param integerNatureSample Most of cases we will measure 'time' with the unit which force integer values
  96   *                            (is more intuitive 850 msecs than 0,850 secs). Then, it is @em true by default.
  97   *                            This is useful to advice better representation for some indicators like minimum/maximum
  98   *                             within integer samples.
  99   *
 100   * @return Assigned concept identification number (sequence)
 101   */
 102   int addConcept(const std::string & description, const std::string & unit, const bool & integerNatureSample = true) throw();
 103
 104
 105   /**
 106   * Stops statistics engine
 107   */
 108   void enable(void) throw() { a_enabled = true; }
 109
 110
 111   /**
 112   * Starts statistics engine
 113   */
 114   void disable(void) throw() { a_enabled = false; }
 115
 116   /**
 117   * Enable sample log for statistics processings. Engine starts with this feature disabled. When a new concept id is added
 118   * to the engine, sample log is also disabled for it.
 119   *
 120   * Sample logs are used to dump each processing for a certain concept identification (<unix timestamp>,<processed value>).
 121   *
 122   *
 123   * @param id Concept identification. If -1 value is provided, all concepts will be activated.
 124   * @param sampleFileName Absolute or relative to execution path, and completed with extension '.<concept id>.csv'. Empty string, disables log. Default file name is 'sample'
 125   *
 126   * @return @em false if not concept is registered with provided id
 127   * @warning Many systems add concepts dynamically. This method only affects to current concepts registered at statistics engine.
 128   */
 129   bool enableSampleLog(const int & id = -1, const char *sampleFileName = NULL) throw();
 130
 131
 132   /**
 133   * Disable sample log for statistics processings
 134   *
 135   * @param id Concept identification.
 136   *
 137   * @return @em false if not concept is registered with provided id
 138   */
 139   bool disableSampleLog(const int & id) throw();
 140
 141   // Gets
 142
 143   /**
 144   * Gets statistic concept information.
 145   *
 146   * @param id Concept identification.
 147   * @param description Concept description returned by reference
 148   * @param unit Concept unit description returned by reference
 149   * @param integerNatureSample nature returned by reference
 150   *
 151   * @return @em false if not concept is registered with provided id
 152   */
 153   bool getConcept(const int & id, std::string & description, std::string & unit, bool & integerNatureSample) const throw();
 154
 155
 156   /**
 157   * Boolean about engine state (enabled / disabled)
 158   */
 159   bool enabled(void) const throw() { return (a_enabled); }
 160
 161
 162   /**
 163   * Class string representation
 164   *
 165   * @return String with class content
 166   */
 167   std::string asString(void) const throw();
 168
 169
 170   /**
 171   * Class XML representation
 172   *
 173   * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
 174   *
 175   * @return XML with class content
 176   */
 177   anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const throw();
 178
 179
 180 private:
 181
 182   Engine(); // private constructor
 183
 184   _concept_identification_map_t a_concept_identification_map;
 185   bool a_enabled;
 186   int a_sequence_concept_id;
 187
 188   bool logSample(const int & conceptId, const anna::Millisecond & unixTimestamp, const double & value) const throw();
 189
 190   friend class anna::Singleton <Engine>;
 191   friend class Accumulator;
 192 };
 193
 194
 195 }
 196 }
 197
 198 #endif