OLD | NEW |
(Empty) | |
| 1 /* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */ |
| 2 /* |
| 3 * Copyright (c) 2016 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 * Modified: Lauri Sormunen <lauri.sormunen@magister.fi> |
| 20 * |
| 21 */ |
| 22 |
| 23 #ifndef STATS_HELPER_H |
| 24 #define STATS_HELPER_H |
| 25 |
| 26 #include <ns3/ptr.h> |
| 27 #include <ns3/object.h> |
| 28 #include <ns3/attribute.h> |
| 29 #include <ns3/net-device-container.h> |
| 30 #include <ns3/node-container.h> |
| 31 #include <map> |
| 32 |
| 33 |
| 34 namespace ns3 { |
| 35 |
| 36 |
| 37 class Node; |
| 38 class CollectorMap; |
| 39 class DataCollectionObject; |
| 40 |
| 41 /** |
| 42 * \ingroup stats |
| 43 * \defgroup stats Statistics |
| 44 * |
| 45 * Data Collection Framework (DCF) implementation on Stats module. For |
| 46 * usage in simulation script, see comments of inherited classes. |
| 47 */ |
| 48 |
| 49 /** |
| 50 * \ingroup stats |
| 51 * \brief Parent abstract class of other statistics helpers. |
| 52 * |
| 53 * A helper is responsible to locate source objects, create probes, collectors, |
| 54 * and aggregators, and connect them together in a proper way to produce the |
| 55 * required statistics. |
| 56 * |
| 57 * The main inputs for the helper are a |
| 58 * name, an identifier type, an output type and nodes which are monitored. |
| 59 * After all the necessary inputs have been set, the statistics |
| 60 * can be started into action by invoking Install(). For example: |
| 61 * \code |
| 62 * NodeContainer nodes; |
| 63 * nodes.Create (2); |
| 64 * // ... (snip) ... |
| 65 * Ptr<StatsAppThroughputHelper> stat |
| 66 * = CreateObject<StatsAppThroughputHelper> (); |
| 67 * stat->SetName ("name"); |
| 68 * stat->SetIdentifierType (StatsHelper::IDENTIFIER_GLOBAL); |
| 69 * stat->SetOutputType (StatsHelper::OUTPUT_SCALAR_FILE); |
| 70 * stat->InstallNodes (nodes); |
| 71 * stat->Install (); |
| 72 * // ... (run simulation) ... |
| 73 * stat->Dispose (); // Disposing creates output files |
| 74 * \endcode |
| 75 * |
| 76 * This parent abstract class hosts several protected methods which are intended |
| 77 * to simplify the development of child classes. These methods handle |
| 78 * tasks related to DCF components. |
| 79 */ |
| 80 class StatsHelper : public Object |
| 81 { |
| 82 public: |
| 83 // COMMON ENUM DATA TYPES /////////////////////////////////////////////////// |
| 84 |
| 85 /** |
| 86 * \enum IdentifierType_t |
| 87 * \brief Possible categorization of statistics output. |
| 88 */ |
| 89 typedef enum |
| 90 { |
| 91 IDENTIFIER_GLOBAL = 0, |
| 92 IDENTIFIER_NODE |
| 93 } IdentifierType_t; |
| 94 |
| 95 /** |
| 96 * \param identifierType an arbitrary identifier type. |
| 97 * \return representation of the identifier type in string. |
| 98 */ |
| 99 static std::string GetIdentifierTypeName (IdentifierType_t identifierType); |
| 100 |
| 101 /** |
| 102 * \enum OutputType_t |
| 103 * \brief Possible types and formats of statistics output. |
| 104 */ |
| 105 typedef enum |
| 106 { |
| 107 OUTPUT_NONE = 0, |
| 108 OUTPUT_SCALAR_FILE, |
| 109 OUTPUT_SCATTER_FILE, |
| 110 OUTPUT_HISTOGRAM_FILE, |
| 111 OUTPUT_PDF_FILE, // probability distribution function |
| 112 OUTPUT_CDF_FILE, // cumulative distribution function |
| 113 OUTPUT_SCALAR_PLOT, |
| 114 OUTPUT_SCATTER_PLOT, |
| 115 OUTPUT_HISTOGRAM_PLOT, |
| 116 OUTPUT_PDF_PLOT, // probability distribution function |
| 117 OUTPUT_CDF_PLOT, // cumulative distribution function |
| 118 } OutputType_t; |
| 119 |
| 120 /** |
| 121 * \param outputType an arbitrary output type. |
| 122 * \return representation of the output type in string. |
| 123 */ |
| 124 static std::string GetOutputTypeName (OutputType_t outputType); |
| 125 |
| 126 // CONSTRUCTOR AND DESTRUCTOR /////////////////////////////////////////////// |
| 127 |
| 128 /** |
| 129 * \brief Creates a new helper instance. |
| 130 */ |
| 131 StatsHelper (); |
| 132 |
| 133 /** |
| 134 * / Destructor. |
| 135 */ |
| 136 virtual ~StatsHelper (); |
| 137 |
| 138 |
| 139 /** |
| 140 * inherited from ObjectBase base class |
| 141 */ |
| 142 static TypeId GetTypeId (); |
| 143 |
| 144 /** |
| 145 * Check if a directory is valid. |
| 146 * \param path Path that is checked |
| 147 */ |
| 148 static bool IsValidDirectory (std::string path); |
| 149 |
| 150 // PUBLIC METHODS /////////////////////////////////////////////////////////// |
| 151 |
| 152 /** |
| 153 * \brief Install the probes, collectors, and aggregators necessary to |
| 154 * produce the statistics output. |
| 155 * |
| 156 * Behaviour should be implemented by child class in DoInstall(). |
| 157 */ |
| 158 void Install (); |
| 159 |
| 160 // SETTER AND GETTER METHODS //////////////////////////////////////////////// |
| 161 |
| 162 /** |
| 163 * \param name string to be prepended on every output file name. |
| 164 */ |
| 165 void SetName (std::string name); |
| 166 |
| 167 /** |
| 168 * \return the name of this helper instance. |
| 169 */ |
| 170 std::string GetName () const; |
| 171 |
| 172 /** |
| 173 * Install nodes to this helper instance. |
| 174 * \param nodes Nodes to which statistics collectors are installed |
| 175 */ |
| 176 void InstallNodes (NodeContainer nodes); |
| 177 |
| 178 /** |
| 179 * Install node to this helper instance. |
| 180 * \param node Node to which statistics collector is installed |
| 181 */ |
| 182 void InstallNodes (Ptr<Node> node); |
| 183 |
| 184 /** |
| 185 * \param identifierType categorization of statistics output. |
| 186 * \warning Does not have any effect if invoked after Install(). |
| 187 */ |
| 188 void SetIdentifierType (IdentifierType_t identifierType); |
| 189 |
| 190 /** |
| 191 * \return the currently active categorization of statistics output. |
| 192 */ |
| 193 IdentifierType_t GetIdentifierType () const; |
| 194 |
| 195 /** |
| 196 * \param outputType types and formats of statistics output. |
| 197 * \warning Does not have any effect if invoked after Install(). |
| 198 */ |
| 199 void SetOutputType (OutputType_t outputType); |
| 200 |
| 201 /** |
| 202 * \return the currently active types and formats of statistics output. |
| 203 */ |
| 204 OutputType_t GetOutputType () const; |
| 205 |
| 206 /** |
| 207 * \return true if Install() has been invoked, otherwise false. |
| 208 */ |
| 209 bool IsInstalled () const; |
| 210 |
| 211 protected: |
| 212 /** |
| 213 * \brief Install the probes, collectors, and aggregators necessary to |
| 214 * produce the statistics output. |
| 215 * |
| 216 * An abstract method of StatsHelper which must be implemented by child |
| 217 * classes. It will be invoked by Install(). |
| 218 */ |
| 219 virtual void DoInstall () = 0; |
| 220 |
| 221 /** |
| 222 * \return the path where statistics output file should be created. |
| 223 * |
| 224 * Path is determined by OutputPath attribute. |
| 225 */ |
| 226 virtual std::string GetOutputPath () const; |
| 227 |
| 228 /** |
| 229 * \param the path where statistics output should be written to. |
| 230 * |
| 231 * Set the default output path. |
| 232 */ |
| 233 virtual void SetOutputPath (std::string outputPath); |
| 234 |
| 235 /** |
| 236 * \brief Compute the path and file name where statistics output should be |
| 237 * written to. |
| 238 * \return path and file name (without extension) |
| 239 * |
| 240 * Path is determined by by OutputPath attribute. |
| 241 */ |
| 242 virtual std::string GetOutputFileName () const; |
| 243 |
| 244 /** |
| 245 * \param dataLabel the short name of the main data of this statistics |
| 246 * \return a string to be printed as the first line of output, consisting of |
| 247 * the identifier title and the given data label |
| 248 */ |
| 249 virtual std::string GetIdentifierHeading (std::string dataLabel) const; |
| 250 |
| 251 /** |
| 252 * \param dataLabel the short name of the main data of this statistics |
| 253 * \return a string to be printed as the first line of output, consisting of |
| 254 * the title of the time column and the given data label |
| 255 */ |
| 256 virtual std::string GetTimeHeading (std::string dataLabel) const; |
| 257 |
| 258 /** |
| 259 * \param dataLabel the short name of the main data of this statistics |
| 260 * \return a string to be printed as the first line of output, consisting of |
| 261 * the given data label and the title of the distribution column |
| 262 */ |
| 263 virtual std::string GetDistributionHeading (std::string dataLabel) const; |
| 264 |
| 265 /** |
| 266 * \brief Create the aggregator according to the output type. |
| 267 * \param aggregatorTypeId the type of aggregator to be created. |
| 268 * \param n1 the name of the attribute to be set on the aggregator created. |
| 269 * \param v1 the value of the attribute to be set on the aggregator created. |
| 270 * \param n2 the name of the attribute to be set on the aggregator created. |
| 271 * \param v2 the value of the attribute to be set on the aggregator created. |
| 272 * \param n3 the name of the attribute to be set on the aggregator created. |
| 273 * \param v3 the value of the attribute to be set on the aggregator created. |
| 274 * \param n4 the name of the attribute to be set on the aggregator created. |
| 275 * \param v4 the value of the attribute to be set on the aggregator created. |
| 276 * \param n5 the name of the attribute to be set on the aggregator created. |
| 277 * \param v5 the value of the attribute to be set on the aggregator created. |
| 278 * \return a pointer to the created aggregator. |
| 279 */ |
| 280 Ptr<DataCollectionObject> CreateAggregator (std::string aggregatorTypeId, |
| 281 std::string n1 = "", |
| 282 const AttributeValue &v1 = EmptyAt
tributeValue (), |
| 283 std::string n2 = "", |
| 284 const AttributeValue &v2 = EmptyAt
tributeValue (), |
| 285 std::string n3 = "", |
| 286 const AttributeValue &v3 = EmptyAt
tributeValue (), |
| 287 std::string n4 = "", |
| 288 const AttributeValue &v4 = EmptyAt
tributeValue (), |
| 289 std::string n5 = "", |
| 290 const AttributeValue &v5 = EmptyAt
tributeValue ()); |
| 291 |
| 292 /** |
| 293 * \brief Create one collector instance for each identifier in the simulation. |
| 294 * \param collectorMap the CollectorMap where the collectors will be created. |
| 295 * \return number of collector instances created. |
| 296 * |
| 297 * The identifier is determined by the currently active identifier type, as |
| 298 * previously selected by SetIdentifierType() method or `IdentifierType` |
| 299 * attribute. Then the method creates identifiers for installed nodes based on |
| 300 * current identifier type, creates a collector instance for each identifier, |
| 301 * assigns the collector instance a name, and put the collector instance into |
| 302 * the CollectorMap. |
| 303 */ |
| 304 uint32_t CreateCollectorPerIdentifier (CollectorMap &collectorMap) const; |
| 305 |
| 306 /** |
| 307 * \brief Get nodes installed to this helper instance. |
| 308 * \return nodes installed |
| 309 */ |
| 310 inline NodeContainer GetNodes () { return m_nodes; }; |
| 311 |
| 312 private: |
| 313 std::string m_name; ///< Name of the helper and file, sho
uld not contain file extension |
| 314 std::string m_outputPath; ///< Output path for statistics files
produced by helper instance |
| 315 IdentifierType_t m_identifierType; ///< Identifier type |
| 316 OutputType_t m_outputType; ///< Output type |
| 317 bool m_isInstalled; ///< Installation status |
| 318 NodeContainer m_nodes; ///< Nodes to which statistics collec
tors are installed |
| 319 |
| 320 }; // end of class StatsHelper |
| 321 |
| 322 |
| 323 } // end of namespace ns3 |
| 324 |
| 325 |
| 326 #endif /* STATS_HELPER_H */ |
OLD | NEW |