1 // ANNA - Anna is Not 'N' Anymore
3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
5 // https://bitbucket.org/testillano/anna
7 // Redistribution and use in source and binary forms, with or without
8 // modification, are permitted provided that the following conditions
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
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.
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.
33 // Authors: eduardo.ramos.testillano@gmail.com
34 // cisco.tierra@gmail.com
37 #ifndef anna_statistics_Engine_hpp
38 #define anna_statistics_Engine_hpp
40 #include <anna/core/Singleton.hpp>
41 #include <anna/core/util/Millisecond.hpp>
48 #include <anna/statistics/Accumulator.hpp>
60 namespace statistics {
65 std::string SampleFile; // Sample file to optional writtings
66 std::string Description;
68 bool IntegerNatureSample;
70 } _concept_identification_t;
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;
79 * Class used to configure general behaviour of statistics processing
80 * By default, the engine is disabled and #enable must be invoked
83 class Engine : public anna::Singleton <Engine> {
91 * Adds a new statistic concept (for example "Time_between_processA_and_processB", "Database time", etc)
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.
100 * @return Assigned concept identification number (sequence)
102 int addConcept(const std::string & description, const std::string & unit, const bool & integerNatureSample = true) throw();
106 * Stops statistics engine
108 void enable(void) throw() { a_enabled = true; }
112 * Starts statistics engine
114 void disable(void) throw() { a_enabled = false; }
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.
120 * Sample logs are used to dump each processing for a certain concept identification (<unix timestamp>,<processed value>).
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'
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.
129 bool enableSampleLog(const int & id = -1, const char *sampleFileName = NULL) throw();
133 * Disable sample log for statistics processings
135 * @param id Concept identification.
137 * @return @em false if not concept is registered with provided id
139 bool disableSampleLog(const int & id) throw();
144 * Gets statistic concept information.
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
151 * @return @em false if not concept is registered with provided id
153 bool getConcept(const int & id, std::string & description, std::string & unit, bool & integerNatureSample) const throw();
157 * Boolean about engine state (enabled / disabled)
159 bool enabled(void) const throw() { return (a_enabled); }
163 * Class string representation
165 * @return String with class content
167 std::string asString(void) const throw();
171 * Class XML representation
173 * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
175 * @return XML with class content
177 anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const throw();
182 Engine(); // private constructor
184 _concept_identification_map_t a_concept_identification_map;
186 int a_sequence_concept_id;
188 bool logSample(const int & conceptId, const anna::Millisecond & unixTimestamp, const double & value) const throw();
190 friend class anna::Singleton <Engine>;
191 friend class Accumulator;