OLD | NEW |
(Empty) | |
| 1 /* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */ |
| 2 /* |
| 3 * Copyright (c) 2014 Magister Solutions |
| 4 * |
| 5 * This program is free software; you can redistribute it and/or modify |
| 6 * it under the terms of the GNU General Public License version 2 as |
| 7 * published by the Free Software Foundation; |
| 8 * |
| 9 * This program is distributed in the hope that it will be useful, |
| 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 12 * GNU General Public License for more details. |
| 13 * |
| 14 * You should have received a copy of the GNU General Public License |
| 15 * along with this program; if not, write to the Free Software |
| 16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 17 * |
| 18 * Author: Budiarto Herman <budiarto.herman@magister.fi> |
| 19 * |
| 20 */ |
| 21 |
| 22 #ifndef UNIT_CONVERSION_COLLECTOR_H |
| 23 #define UNIT_CONVERSION_COLLECTOR_H |
| 24 |
| 25 #include <ns3/data-collection-object.h> |
| 26 #include <ns3/traced-value.h> |
| 27 #include <ns3/traced-callback.h> |
| 28 #include <ns3/nstime.h> |
| 29 |
| 30 |
| 31 namespace ns3 { |
| 32 |
| 33 /** |
| 34 * \ingroup aggregator |
| 35 * \brief Collector which converts input sample data to a different unit. |
| 36 * |
| 37 * ### Input ### |
| 38 * This class provides 9 trace sinks for receiving inputs. Each trace sink |
| 39 * is a function with a signature similar to the following: |
| 40 * \code |
| 41 * void TraceSinkP (P oldData, P newData); |
| 42 * \endcode |
| 43 * where `P` is one of the 9 supported data types. This type of signature |
| 44 * follows the trace source signature types commonly exported by probes. |
| 45 * Although different data types are accepted, they are all internally |
| 46 * processed using `double` data type. |
| 47 * |
| 48 * ### Processing ### |
| 49 * This class provides 7 types of unit conversion procedure. It can be selected |
| 50 * by calling the SetConversionType() method or setting the `ConversionType` |
| 51 * attribute. |
| 52 * - `TRANSPARENT` (no conversion at all) |
| 53 * - `FROM_BYTES_TO_BIT` |
| 54 * - `FROM_BYTES_TO_KBIT` |
| 55 * - `FROM_BYTES_TO_MBIT` |
| 56 * - `FROM_SECONDS_TO_MS` |
| 57 * - `FROM_LINEAR_TO_DB` |
| 58 * - `FROM_LINEAR_TO_DBM` |
| 59 * |
| 60 * ### Output ### |
| 61 * This class utilizes 3 trace sources to export the converted data: |
| 62 * - `Output`: the converted old data and the converted new data (similar |
| 63 * signature as probe's trace source, hence can be used to export to another |
| 64 * collector). |
| 65 * - `OutputValue`: the converted new data. |
| 66 * - `OutputTimeValue`: the current simulation time and the converted new data. |
| 67 * All of the above information are exported using `double` data type in the |
| 68 * unit specified by the selected conversion type. An exception here is in the |
| 69 * trace source `OutputTimeValue` where the time information is exported in |
| 70 * unit of seconds by default, or as specified otherwise by calling the |
| 71 * SetTimeUnit() method or setting the `TimeUnit` attribute. |
| 72 */ |
| 73 class UnitConversionCollector : public DataCollectionObject |
| 74 { |
| 75 public: |
| 76 /** |
| 77 * \enum ConversionType_t |
| 78 * \brief Types of unit conversion procedure supported by this class. |
| 79 * |
| 80 * \note Conversion to dB and dBm units expect strictly positive input value. |
| 81 */ |
| 82 typedef enum |
| 83 { |
| 84 TRANSPARENT = 0, ///< No conversion at all (the default). |
| 85 FROM_BYTES_TO_BIT, ///< Input in bytes and output in bits. |
| 86 FROM_BYTES_TO_KBIT, ///< Input in bytes and output in kilobits. |
| 87 FROM_BYTES_TO_MBIT, ///< Input in bytes and output in megabits. |
| 88 FROM_SECONDS_TO_MS, ///< Input in seconds and output in milliseconds. |
| 89 FROM_LINEAR_TO_DB, ///< Input in linear unit and output in decibel (dB). |
| 90 FROM_LINEAR_TO_DBM ///< Input in linear unit and output in decibel (dBm). |
| 91 } ConversionType_t; |
| 92 |
| 93 /** |
| 94 * \param conversionType an arbitrary type of unit conversion procedure. |
| 95 * \return representation of the type in string. |
| 96 */ |
| 97 static std::string GetConversionTypeName (ConversionType_t conversionType); |
| 98 |
| 99 /// Creates a new collector instance. |
| 100 UnitConversionCollector (); |
| 101 |
| 102 // inherited from ObjectBase base class |
| 103 static TypeId GetTypeId (); |
| 104 |
| 105 // ATTRIBUTE SETTERS AND GETTERS //////////////////////////////////////////// |
| 106 |
| 107 /** |
| 108 * \param conversionType the type of unit conversion procedure to be utilized |
| 109 * by this collector instance to process the incoming |
| 110 * samples. |
| 111 */ |
| 112 void SetConversionType (ConversionType_t conversionType); |
| 113 |
| 114 /** |
| 115 * \return the type of unit conversion procedure to be utilized by this |
| 116 * collector instance to process the incoming samples. |
| 117 */ |
| 118 ConversionType_t GetConversionType () const; |
| 119 |
| 120 /** |
| 121 * \param unit the unit used for the time output. |
| 122 */ |
| 123 void SetTimeUnit (Time::Unit unit); |
| 124 |
| 125 /** |
| 126 * \return the unit used for the time output. |
| 127 */ |
| 128 Time::Unit GetTimeUnit () const; |
| 129 |
| 130 // TRACE SINKS ////////////////////////////////////////////////////////////// |
| 131 |
| 132 /** |
| 133 * \brief Trace sink for receiving data from `double` valued trace sources. |
| 134 * \param oldData the original value. |
| 135 * \param newData the new value. |
| 136 * |
| 137 * This method serves as a trace sink to `double` valued trace sources. |
| 138 * |
| 139 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 140 * argument is regarded as zero at the very first sample. |
| 141 */ |
| 142 void TraceSinkDouble (double oldData, double newData); |
| 143 |
| 144 /** |
| 145 * \brief Trace sink for receiving data from `int8_t` valued trace sources. |
| 146 * \param oldData the original value. |
| 147 * \param newData the new value. |
| 148 * |
| 149 * This method serves as a trace sink to `int8_t` valued trace sources. |
| 150 * The data will be converted to double and then simply passed to the |
| 151 * TraceSinkDouble() method. |
| 152 * |
| 153 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 154 * argument is regarded as zero at the very first sample. |
| 155 */ |
| 156 void TraceSinkInteger8 (int8_t oldData, int8_t newData); |
| 157 |
| 158 /** |
| 159 * \brief Trace sink for receiving data from `int16_t` valued trace sources. |
| 160 * \param oldData the original value. |
| 161 * \param newData the new value. |
| 162 * |
| 163 * This method serves as a trace sink to `int16_t` valued trace sources. |
| 164 * The data will be converted to double and then simply passed to the |
| 165 * TraceSinkDouble() method. |
| 166 * |
| 167 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 168 * argument is regarded as zero at the very first sample. |
| 169 */ |
| 170 void TraceSinkInteger16 (int16_t oldData, int16_t newData); |
| 171 |
| 172 /** |
| 173 * \brief Trace sink for receiving data from `int32_t` valued trace sources. |
| 174 * \param oldData the original value. |
| 175 * \param newData the new value. |
| 176 * |
| 177 * This method serves as a trace sink to `int32_t` valued trace sources. |
| 178 * The data will be converted to double and then simply passed to the |
| 179 * TraceSinkDouble() method. |
| 180 * |
| 181 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 182 * argument is regarded as zero at the very first sample. |
| 183 */ |
| 184 void TraceSinkInteger32 (int32_t oldData, int32_t newData); |
| 185 |
| 186 /** |
| 187 * \brief Trace sink for receiving data from `int64_t` valued trace sources. |
| 188 * \param oldData the original value. |
| 189 * \param newData the new value. |
| 190 * |
| 191 * This method serves as a trace sink to `int64_t` valued trace sources. |
| 192 * The data will be converted to double and then simply passed to the |
| 193 * TraceSinkDouble() method. |
| 194 * |
| 195 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 196 * argument is regarded as zero at the very first sample. |
| 197 */ |
| 198 void TraceSinkInteger64 (int64_t oldData, int64_t newData); |
| 199 |
| 200 /** |
| 201 * \brief Trace sink for receiving data from `uint8_t` valued trace sources. |
| 202 * \param oldData the original value. |
| 203 * \param newData the new value. |
| 204 * |
| 205 * This method serves as a trace sink to `uint8_t` valued trace sources. |
| 206 * The data will be converted to double and then simply passed to the |
| 207 * TraceSinkDouble() method. |
| 208 * |
| 209 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 210 * argument is regarded as zero at the very first sample. |
| 211 */ |
| 212 void TraceSinkUinteger8 (uint8_t oldData, uint8_t newData); |
| 213 |
| 214 /** |
| 215 * \brief Trace sink for receiving data from `uint16_t` valued trace sources. |
| 216 * \param oldData the original value. |
| 217 * \param newData the new value. |
| 218 * |
| 219 * This method serves as a trace sink to `uint16_t` valued trace sources. |
| 220 * The data will be converted to double and then simply passed to the |
| 221 * TraceSinkDouble() method. |
| 222 * |
| 223 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 224 * argument is regarded as zero at the very first sample. |
| 225 */ |
| 226 void TraceSinkUinteger16 (uint16_t oldData, uint16_t newData); |
| 227 |
| 228 /** |
| 229 * \brief Trace sink for receiving data from `uint32_t` valued trace sources. |
| 230 * \param oldData the original value. |
| 231 * \param newData the new value. |
| 232 * |
| 233 * This method serves as a trace sink to `uint32_t` valued trace sources. |
| 234 * The data will be converted to double and then simply passed to the |
| 235 * TraceSinkDouble() method. |
| 236 * |
| 237 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 238 * argument is regarded as zero at the very first sample. |
| 239 */ |
| 240 void TraceSinkUinteger32 (uint32_t oldData, uint32_t newData); |
| 241 |
| 242 /** |
| 243 * \brief Trace sink for receiving data from `uint64_t` valued trace sources. |
| 244 * \param oldData the original value. |
| 245 * \param newData the new value. |
| 246 * |
| 247 * This method serves as a trace sink to `uint64_t` valued trace sources. |
| 248 * The data will be converted to double and then simply passed to the |
| 249 * TraceSinkDouble() method. |
| 250 * |
| 251 * \warning In order to avoid processing uninitialized values, the `oldData` |
| 252 * argument is regarded as zero at the very first sample. |
| 253 */ |
| 254 void TraceSinkUinteger64 (uint64_t oldData, uint64_t newData); |
| 255 |
| 256 protected: |
| 257 // Inherited from Object base class |
| 258 virtual void DoDispose (); |
| 259 |
| 260 /** |
| 261 * \internal |
| 262 * \param original the new sample data received by trace sink. |
| 263 * \return the sample data converted by the selected unit conversion |
| 264 * procedure. |
| 265 * |
| 266 * The unit conversion procedure can be selected by calling |
| 267 * the SetConversionType() method or setting the `ConversionType` attribute. |
| 268 */ |
| 269 virtual double Convert (double original) const; |
| 270 |
| 271 private: |
| 272 /** |
| 273 * \brief Indicate that the next sample would be the first sample received. |
| 274 * |
| 275 * The first sample of data received from the probe usually contains |
| 276 * uninitialized old data values. This fact makes Valgrind unhappy. Because |
| 277 * of this, the trace sinks "force initialize" the first sample of this old |
| 278 * data value to zero. |
| 279 */ |
| 280 bool m_isFirstSample; |
| 281 |
| 282 ConversionType_t m_conversionType; ///< `ConversionType` attribute. |
| 283 Time::Unit m_timeUnit; ///< `TimeUnit` attribute. |
| 284 |
| 285 TracedCallback<double, double> m_output; ///< `Output` trace source. |
| 286 TracedCallback<double> m_outputValue; ///< `OutputValue` trace source. |
| 287 TracedCallback<double, double> m_outputTimeValue; ///< `OutputTimeValue` trace
source. |
| 288 |
| 289 }; // end of class UnitConversionCollector |
| 290 |
| 291 |
| 292 } // end of namespace ns3 |
| 293 |
| 294 |
| 295 #endif /* UNIT_CONVERSION_COLLECTOR_H */ |
OLD | NEW |