1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 2 /* 3 * Copyright (c) 2013 University of Washington 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: Mitch Watrous (watrous@u.washington.edu) 19 */ 20 21 #ifndef GNUPLOT_HELPER_H 22 #define GNUPLOT_HELPER_H 23 24 #include <map> 25 #include <utility> 26 #include <string> 27 #include "ns3/object-factory.h" 28 #include "ns3/ptr.h" 29 #include "ns3/probe.h" 30 #include "ns3/gnuplot-aggregator.h" 31 #include "ns3/time-series-adaptor.h" 32 33 namespace ns3 { 34 35 /** 36 * \ingroup gnuplot 37 * \brief Helper class used to make gnuplot plots. 38 **/ 39 class GnuplotHelper 40 { 41 public: 42 /** 43 * Constructs a gnuplot helper that will create a space separated 44 * gnuplot data file named "gnuplot-helper.dat", a gnuplot control 45 * file named "gnuplot-helper.plt", and a shell script to generate 46 * the gnuplot named "gnuplot-helper.sh" unless it is later 47 * configured otherwise. 48 */ 49 GnuplotHelper (); 50 51 /** 52 * \param outputFileNameWithoutExtension name of gnuplot related files to 53 * write with no extension 54 * \param title plot title string to use for this plot. 55 * \param xLegend the legend for the x horizontal axis. 56 * \param yLegend the legend for the y vertical axis. 57 * \param terminalType terminal type setting string for output. The 58 * default terminal type is "png" 59 * 60 * Constructs a gnuplot helper that will create a space separated 61 * gnuplot data file named outputFileNameWithoutExtension + ".dat", 62 * a gnuplot control file named outputFileNameWithoutExtension + 63 * ".plt", and a shell script to generate the gnuplot named 64 * outputFileNameWithoutExtension + ".sh". 65 */ 66 GnuplotHelper (const std::string &outputFileNameWithoutExtension, 67 const std::string &title, 68 const std::string &xLegend, 69 const std::string &yLegend, 70 const std::string &terminalType = "png"); 71 72 virtual ~GnuplotHelper (); 73 74 /** 75 * \param outputFileNameWithoutExtension name of gnuplot related files to 76 * write with no extension 77 * \param title plot title string to use for this plot. 78 * \param xLegend the legend for the x horizontal axis. 79 * \param yLegend the legend for the y vertical axis. 80 * \param terminalType terminal type setting string for output. The 81 * default terminal type is "png" 82 * 83 * Configures plot related parameters for this gnuplot helper so 84 * that it will create a space separated gnuplot data file named 85 * outputFileNameWithoutExtension + ".dat", a gnuplot control file 86 * named outputFileNameWithoutExtension + ".plt", and a shell script 87 * to generate the gnuplot named outputFileNameWithoutExtension + 88 * ".sh". 89 */ 90 void ConfigurePlot (const std::string &outputFileNameWithoutExtension, 91 const std::string &title, 92 const std::string &xLegend, 93 const std::string &yLegend, 94 const std::string &terminalType = "png"); 95 96 /** 97 * \param typeId the type ID for the probe used when it is created. 98 * \param path Config path for underlying trace source to be probed 99 * \param probeTraceSource the probe trace source to access. 100 * \param title the title to be associated to this dataset 101 * \param keyLocation the location of the key in the plot. 102 * 103 * Plots a dataset generated by hooking the ns-3 trace source with a 104 * probe, and then plot the values from the probeTraceSource. The dataset 105 * will have the provided title, and will consist of the 'newValue' 106 * at each timestamp. 107 * 108 * This method will create one or more probes according to the TypeId 109 * provided, connect the probe(s) to the trace source specified by 110 * the config path, and hook the probeTraceSource(s) to the downstream 111 * aggregator. 112 * 113 * If the config path has more than one match in the system 114 * (e.g. there is a wildcard), then one dataset for each match will 115 * be plotted. The dataset titles will be suffixed with the matched 116 * characters for each of the wildcards in the config path, 117 * separated by spaces. For example, if the proposed dataset title 118 * is the string "bytes", and there are two wildcards in the path, 119 * then dataset titles like "bytes-0 0" or "bytes-12 9" will be 120 * possible as labels for the datasets that are plotted. 121 */ 122 void PlotProbe (const std::string &typeId, 123 const std::string &path, 124 const std::string &probeTraceSource, 125 const std::string &title, 126 enum GnuplotAggregator::KeyLocation keyLocation = GnuplotAggregator::KEY_INSIDE); 127 128 /** 129 * \param adaptorName the timeSeriesAdaptor's name. 130 * 131 * \brief Adds a time series adaptor to be used to make the plot. 132 */ 133 void AddTimeSeriesAdaptor (const std::string &adaptorName); 134 135 /** 136 * \param probeName the probe's name. 137 * \return Ptr to probe 138 * \brief Gets the specified probe. 139 */ 140 Ptr<Probe> GetProbe (std::string probeName) const; 141 142 /** 143 * \return Ptr to GnuplotAggregator object 144 * \brief Gets the aggregator. 145 * 146 * This function is non-const because an aggregator may be lazily 147 * created by this method. 148 */ 149 Ptr<GnuplotAggregator> GetAggregator (); 150 151 private: 152 153 /** 154 * \param typeId the type ID for the probe used when it is created. 155 * \param probeName the probe's name. 156 * \param path Config path to access the probe. 157 * 158 * \brief Adds a probe to be used to make the plot. 159 */ 160 void AddProbe (const std::string &typeId, 161 const std::string &probeName, 162 const std::string &path); 163 164 /** 165 * \brief Constructs the aggregator. 166 */ 167 void ConstructAggregator (); 168 169 /** 170 * \param typeId the type ID for the probe used when it is created. 171 * \param matchIdentifier this string is used to make the probe's 172 * context be unique. 173 * \param path Config path to access the probe. 174 * \param probeTraceSource the probe trace source to access. 175 * \param title the title to be associated to this dataset. 176 * 177 * \brief Connects the probe to the aggregator. 178 */ 179 void ConnectProbeToAggregator (const std::string &typeId, 180 const std::string &matchIdentifier, 181 const std::string &path, 182 const std::string &probeTraceSource, 183 const std::string &title); 184 185 /// Used to create the probes and collectors as they are added. 186 ObjectFactory m_factory; 187 188 /// The aggregator used to make the plots. 189 Ptr<GnuplotAggregator> m_aggregator; 190 191 /// Maps probe names to probes. 192 std::map<std::string, std::pair <Ptr<Probe>, std::string> > m_probeMap; 193 194 /// Maps time series adaptor names to time series adaptors. 195 std::map<std::string, Ptr<TimeSeriesAdaptor> > m_timeSeriesAdaptorMap; 196 197 /// Number of plot probes that have been created. 198 uint32_t m_plotProbeCount; 199 200 /// The name of the output file to created without its extension. 201 std::string m_outputFileNameWithoutExtension; 202 203 /// Title string to use for this plot. 204 std::string m_title; 205 206 /// Legend for the x axis. 207 std::string m_xLegend; 208 209 /// Legend for the y axis. 210 std::string m_yLegend; 211 212 /// Terminal type for the plot. 213 std::string m_terminalType; 214 215 }; // class GnuplotHelper 216 217 218 } // namespace ns3 219 220 #endif // GNUPLOT_HELPER_H 221