A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
file-helper.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2013 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mitch Watrous (watrous@u.washington.edu)
7 */
8
9#ifndef FILE_HELPER_H
10#define FILE_HELPER_H
11
12#include "ns3/file-aggregator.h"
13#include "ns3/object-factory.h"
14#include "ns3/probe.h"
15#include "ns3/ptr.h"
16#include "ns3/time-series-adaptor.h"
17
18#include <map>
19#include <string>
20
21namespace ns3
22{
23
24/**
25 * \ingroup stats
26 * \brief Helper class used to put data values into a file.
27 **/
29{
30 public:
31 /**
32 * Constructs a file helper that will create a space separated file
33 * named "file-helper.txt" unless it is later configured otherwise.
34 */
35 FileHelper();
36
37 /**
38 * \param outputFileNameWithoutExtension name of output file to
39 * write with no extension
40 * \param fileType type of file to write.
41 *
42 * Constructs a file helper that will create a file named
43 * outputFileNameWithoutExtension plus possible extra information
44 * from wildcard matches plus ".txt" with values printed as
45 * specified by fileType. The default file type is space-separated.
46 */
47 FileHelper(const std::string& outputFileNameWithoutExtension,
49
50 virtual ~FileHelper();
51
52 /**
53 * \param outputFileNameWithoutExtension name of output file to
54 * write with no extension
55 * \param fileType type of file to write.
56 *
57 * Configures file related parameters for this file helper so that
58 * it will create a file named outputFileNameWithoutExtension plus
59 * possible extra information from wildcard matches plus ".txt" with
60 * values printed as specified by fileType. The default file type
61 * is space-separated.
62 */
63 void ConfigureFile(const std::string& outputFileNameWithoutExtension,
65
66 /**
67 * \param typeId the type ID for the probe used when it is created.
68 * \param path Config path for underlying trace source to be probed
69 * \param probeTraceSource the probe trace source to access.
70 *
71 * Creates output files generated by hooking the ns-3 trace source
72 * with a probe, and then writing the values from the
73 * probeTraceSource. The output file names will have the text stored
74 * in m_outputFileNameWithoutExtension plus ".txt", and will consist
75 * of the 'newValue' at each timestamp.
76 *
77 * This method will create one or more probes according to the TypeId
78 * provided, connect the probe(s) to the trace source specified by
79 * the config path, and hook the probeTraceSource(s) to the downstream
80 * aggregator.
81 *
82 * If the config path has more than one match in the system
83 * (e.g. there is a wildcard), then one output file for each match
84 * will be created. The output file names will contain the text in
85 * m_outputFileNameWithoutExtension plus the matched characters for
86 * each of the wildcards in the config path, separated by dashes,
87 * plus ".txt". For example, if the value in
88 * m_outputFileNameWithoutExtension is the string
89 * "packet-byte-count", and there are two wildcards in the path,
90 * then output file names like "packet-byte-count-0-0.txt" or
91 * "packet-byte-count-12-9.txt" will be possible as names for the
92 * files that will be created.
93 *
94 * A fatal error will result if an unknown probe type is used.
95 */
96 void WriteProbe(const std::string& typeId,
97 const std::string& path,
98 const std::string& probeTraceSource);
99
100 /**
101 * \param adaptorName the timeSeriesAdaptor's name.
102 *
103 * \brief Adds a time series adaptor to be used to write the file.
104 */
105 void AddTimeSeriesAdaptor(const std::string& adaptorName);
106
107 /**
108 * \param aggregatorName the aggregator's name.
109 * \param outputFileName name of the file to write.
110 * \param onlyOneAggregator indicates if more than one aggregator
111 * should be created or not.
112 *
113 * \brief Adds an aggregator to be used to write values to files.
114 */
115 void AddAggregator(const std::string& aggregatorName,
116 const std::string& outputFileName,
117 bool onlyOneAggregator);
118
119 /**
120 * \param probeName the probe's name.
121 * \return Ptr to the probe
122 * \brief Gets the specified probe.
123 */
124 Ptr<Probe> GetProbe(std::string probeName) const;
125
126 /**
127 * \return Ptr to a FileAggregator object
128 * \brief Gets the single aggregator that is always constructed.
129 *
130 * This function is non-const because an aggregator may be lazily
131 * created by this method.
132 */
134
135 /**
136 * \param aggregatorName name for aggregator.
137 * \param outputFileName name of output file to write.
138 * \return Ptr to a FileAggregator object
139 * \brief Gets one of the multiple aggregators from the map.
140 *
141 * This function is non-const because an aggregator may be lazily
142 * created by this method.
143 */
144 Ptr<FileAggregator> GetAggregatorMultiple(const std::string& aggregatorName,
145 const std::string& outputFileName);
146
147 /**
148 * \param heading the heading string.
149 *
150 * \brief Sets the heading string that will be printed on the first
151 * line of the file.
152 *
153 * Note that the heading string will only be printed if it has been
154 * set by calling this function.
155 */
156 void SetHeading(const std::string& heading);
157
158 /**
159 * \param format the 1D format string.
160 *
161 * \brief Sets the 1D format string for the C-style sprintf()
162 * function.
163 */
164 void Set1dFormat(const std::string& format);
165
166 /**
167 * \param format the 2D format string.
168 *
169 * \brief Sets the 2D format string for the C-style sprintf()
170 * function.
171 */
172 void Set2dFormat(const std::string& format);
173
174 /**
175 * \param format the 3D format string.
176 *
177 * \brief Sets the 3D format string for the C-style sprintf()
178 * function.
179 */
180 void Set3dFormat(const std::string& format);
181
182 /**
183 * \param format the 4D format string.
184 *
185 * \brief Sets the 4D format string for the C-style sprintf()
186 * function.
187 */
188 void Set4dFormat(const std::string& format);
189
190 /**
191 * \param format the 5D format string.
192 *
193 * \brief Sets the 5D format string for the C-style sprintf()
194 * function.
195 */
196 void Set5dFormat(const std::string& format);
197
198 /**
199 * \param format the 6D format string.
200 *
201 * \brief Sets the 6D format string for the C-style sprintf()
202 * function.
203 */
204 void Set6dFormat(const std::string& format);
205
206 /**
207 * \param format the 7D format string.
208 *
209 * \brief Sets the 7D format string for the C-style sprintf()
210 * function.
211 */
212 void Set7dFormat(const std::string& format);
213
214 /**
215 * \param format the 8D format string.
216 *
217 * \brief Sets the 8D format string for the C-style sprintf()
218 * function.
219 */
220 void Set8dFormat(const std::string& format);
221
222 /**
223 * \param format the 9D format string.
224 *
225 * \brief Sets the 9D format string for the C-style sprintf()
226 * function.
227 */
228 void Set9dFormat(const std::string& format);
229
230 /**
231 * \param format the 10D format string.
232 *
233 * \brief Sets the 10D format string for the C-style sprintf()
234 * function.
235 */
236 void Set10dFormat(const std::string& format);
237
238 private:
239 /**
240 * \param typeId the type ID for the probe used when it is created.
241 * \param probeName the probe's name.
242 * \param path Config path to access the probe
243 *
244 * \brief Adds a probe to be used to write values to files.
245 */
246 void AddProbe(const std::string& typeId, const std::string& probeName, const std::string& path);
247
248 /**
249 * \param typeId the type ID for the probe used when it is created.
250 * \param matchIdentifier this string is used to make the probe's
251 * context be unique.
252 * \param path Config path to access the probe.
253 * \param probeTraceSource the probe trace source to access.
254 * \param outputFileNameWithoutExtension name of output file to
255 * write with no extension
256 * \param onlyOneAggregator indicates if more than one aggregator
257 * should be created or not.
258 *
259 * \brief Connects the probe to the aggregator.
260 *
261 * A fatal error will result if an unknown probe type is used.
262 */
263 void ConnectProbeToAggregator(const std::string& typeId,
264 const std::string& matchIdentifier,
265 const std::string& path,
266 const std::string& probeTraceSource,
267 const std::string& outputFileNameWithoutExtension,
268 bool onlyOneAggregator);
269
270 /// Used to create the probes and collectors as they are added.
272
273 /// The single aggregator that is always created in the constructor.
275
276 /// Maps aggregator names to aggregators when multiple aggregators
277 /// are needed.
278 std::map<std::string, Ptr<FileAggregator>> m_aggregatorMap;
279
280 /// Maps probe names to probes.
281 std::map<std::string, std::pair<Ptr<Probe>, std::string>> m_probeMap;
282
283 /// Maps time series adaptor names to time series adaptors.
284 std::map<std::string, Ptr<TimeSeriesAdaptor>> m_timeSeriesAdaptorMap;
285
286 /// Number of file probes that have been created.
288
289 /// Determines the kind of file written by the aggregator.
291
292 /// The name of the output file to created without its extension.
294
295 /// Indicates if the heading line for the file has been set.
297
298 /// Heading line for the outputfile.
299 std::string m_heading;
300
301 std::string m_1dFormat; //!< Format string for 1D format C-style sprintf() function.
302 std::string m_2dFormat; //!< Format string for 2D format C-style sprintf() function.
303 std::string m_3dFormat; //!< Format string for 3D format C-style sprintf() function.
304 std::string m_4dFormat; //!< Format string for 4D format C-style sprintf() function.
305 std::string m_5dFormat; //!< Format string for 5D format C-style sprintf() function.
306 std::string m_6dFormat; //!< Format string for 6D format C-style sprintf() function.
307 std::string m_7dFormat; //!< Format string for 7D format C-style sprintf() function.
308 std::string m_8dFormat; //!< Format string for 8D format C-style sprintf() function.
309 std::string m_9dFormat; //!< Format string for 9D format C-style sprintf() function.
310 std::string m_10dFormat; //!< Format string for 10D format C-style sprintf() function.
311
312}; // class FileHelper
313
314} // namespace ns3
315
316#endif // FILE_HELPER_H
FileType
The type of file written by the aggregator.
Helper class used to put data values into a file.
Definition file-helper.h:29
void Set2dFormat(const std::string &format)
Sets the 2D format string for the C-style sprintf() function.
void SetHeading(const std::string &heading)
Sets the heading string that will be printed on the first line of the file.
void Set5dFormat(const std::string &format)
Sets the 5D format string for the C-style sprintf() function.
void AddTimeSeriesAdaptor(const std::string &adaptorName)
Adds a time series adaptor to be used to write the file.
Ptr< FileAggregator > GetAggregatorSingle()
Gets the single aggregator that is always constructed.
std::string m_6dFormat
Format string for 6D format C-style sprintf() function.
std::map< std::string, std::pair< Ptr< Probe >, std::string > > m_probeMap
Maps probe names to probes.
void Set3dFormat(const std::string &format)
Sets the 3D format string for the C-style sprintf() function.
Ptr< Probe > GetProbe(std::string probeName) const
Gets the specified probe.
std::map< std::string, Ptr< TimeSeriesAdaptor > > m_timeSeriesAdaptorMap
Maps time series adaptor names to time series adaptors.
void WriteProbe(const std::string &typeId, const std::string &path, const std::string &probeTraceSource)
std::map< std::string, Ptr< FileAggregator > > m_aggregatorMap
Maps aggregator names to aggregators when multiple aggregators are needed.
FileHelper()
Constructs a file helper that will create a space separated file named "file-helper....
void Set6dFormat(const std::string &format)
Sets the 6D format string for the C-style sprintf() function.
ObjectFactory m_factory
Used to create the probes and collectors as they are added.
uint32_t m_fileProbeCount
Number of file probes that have been created.
std::string m_heading
Heading line for the outputfile.
std::string m_outputFileNameWithoutExtension
The name of the output file to created without its extension.
std::string m_8dFormat
Format string for 8D format C-style sprintf() function.
std::string m_9dFormat
Format string for 9D format C-style sprintf() function.
void ConfigureFile(const std::string &outputFileNameWithoutExtension, FileAggregator::FileType fileType=FileAggregator::SPACE_SEPARATED)
bool m_hasHeadingBeenSet
Indicates if the heading line for the file has been set.
std::string m_2dFormat
Format string for 2D format C-style sprintf() function.
void AddAggregator(const std::string &aggregatorName, const std::string &outputFileName, bool onlyOneAggregator)
Adds an aggregator to be used to write values to files.
void Set1dFormat(const std::string &format)
Sets the 1D format string for the C-style sprintf() function.
void AddProbe(const std::string &typeId, const std::string &probeName, const std::string &path)
Adds a probe to be used to write values to files.
std::string m_1dFormat
Format string for 1D format C-style sprintf() function.
std::string m_10dFormat
Format string for 10D format C-style sprintf() function.
std::string m_4dFormat
Format string for 4D format C-style sprintf() function.
std::string m_7dFormat
Format string for 7D format C-style sprintf() function.
void Set4dFormat(const std::string &format)
Sets the 4D format string for the C-style sprintf() function.
void Set7dFormat(const std::string &format)
Sets the 7D format string for the C-style sprintf() function.
FileAggregator::FileType m_fileType
Determines the kind of file written by the aggregator.
Ptr< FileAggregator > m_aggregator
The single aggregator that is always created in the constructor.
virtual ~FileHelper()
std::string m_5dFormat
Format string for 5D format C-style sprintf() function.
std::string m_3dFormat
Format string for 3D format C-style sprintf() function.
void Set8dFormat(const std::string &format)
Sets the 8D format string for the C-style sprintf() function.
Ptr< FileAggregator > GetAggregatorMultiple(const std::string &aggregatorName, const std::string &outputFileName)
Gets one of the multiple aggregators from the map.
void Set10dFormat(const std::string &format)
Sets the 10D format string for the C-style sprintf() function.
void ConnectProbeToAggregator(const std::string &typeId, const std::string &matchIdentifier, const std::string &path, const std::string &probeTraceSource, const std::string &outputFileNameWithoutExtension, bool onlyOneAggregator)
Connects the probe to the aggregator.
void Set9dFormat(const std::string &format)
Sets the 9D format string for the C-style sprintf() function.
Instantiate subclasses of ns3::Object.
Smart pointer class similar to boost::intrusive_ptr.
Every class exported by the ns3 library is enclosed in the ns3 namespace.