1 // ANNA - Anna is Not Nothingness Anymore //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo //
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 //
9 #ifndef anna_statistics_Engine_hpp
10 #define anna_statistics_Engine_hpp
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>
22 #include <anna/statistics/Accumulator.hpp>
34 namespace statistics {
42 std::string SampleFile; // Sample file to optional writtings
43 std::string Description;
45 bool IntegerNatureSample;
47 } _concept_identification_t;
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;
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;
59 * Class used to configure general behaviour of statistics processing
60 * By default, the engine is disabled and #enable must be invoked
63 class Engine : public anna::Singleton <Engine> {
74 * Adds a new statistic concept (for example "Time_between_processA_and_processB", "Database time", etc)
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.
83 * @return Assigned concept identification number (sequence)
85 int addConcept(const std::string & description, const std::string & unit, const bool & integerNatureSample = true) throw();
89 * Stops statistics engine
91 void enable(void) throw() { a_enabled = true; }
95 * Starts statistics engine
97 void disable(void) throw() { a_enabled = false; }
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.
103 * Sample logs are used to dump each processing for a certain concept identification (<unix timestamp>,<processed value>).
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'
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.
112 bool enableSampleLog(const int & id = -1, const char *sampleFileName = NULL) throw();
116 * Disable sample log for statistics processings
118 * @param id Concept identification. If -1 value is provided, all concepts will be deactivated.
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.
123 bool disableSampleLog(const int & id = -1) throw();
128 * Gets statistic concept information.
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
135 * @return @em false if not concept is registered with provided id
137 bool getConcept(const int & id, std::string & description, std::string & unit, bool & integerNatureSample) const throw();
141 * Boolean about engine state (enabled / disabled)
143 bool enabled(void) const throw() { return (a_enabled); }
147 * Creates a statistic accumulator
149 * @param name Accumulator name
151 * \return The accumulator created or exception when already exists for the provided name.
153 Accumulator *createAccumulator(const std::string &name) throw(anna::RuntimeException);
156 * Returns accumulator instance identified by name.
158 * \param name Accumulator name
160 * \return The accumulator instance identified by name provided, NULL if not found
162 Accumulator* getAccumulator(const std::string &name) throw();
167 * Class string representation
169 * @return String with class content
171 std::string asString(void) const throw();
175 * Class XML representation
177 * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
179 * @return XML with class content
181 anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const throw();
186 Engine(); // private constructor
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
191 int a_sequence_concept_id;
192 anna::Mutex a_mutex; // for logSample
194 bool logSample(const int & conceptId, const anna::Millisecond & unixTimestamp, const double & value) const throw();
196 friend class anna::Singleton <Engine>;
197 friend class Accumulator;