Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(952)

Unified Diff: doc/tutorial/source/data-collection.rst

Issue 245260043: DCF collectors
Patch Set: Created 8 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
Index: doc/tutorial/source/data-collection.rst
===================================================================
--- a/doc/tutorial/source/data-collection.rst
+++ b/doc/tutorial/source/data-collection.rst
@@ -7,8 +7,8 @@
---------------
Our final tutorial chapter introduces some components that were added
-to |ns3| in version 3.18, and that are still under development. This
-tutorial section is also a work-in-progress.
+to |ns3| starting with version 3.18, and that are still under development.
+This tutorial section is also a work-in-progress.
Motivation
**********
@@ -122,22 +122,20 @@
+ GnuplotHelper plotHelper;
+
+ // Configure the plot. The first argument is the file name prefix
- + // for the output files generated. The second, third, and fourth
- + // arguments are, respectively, the plot title, x-axis, and y-axis labels
- + plotHelper.ConfigurePlot ("seventh-packet-byte-count",
- + "Packet Byte Count vs. Time",
- + "Time (Seconds)",
- + "Packet Byte Count");
- +
- + // Specify the probe type, trace source path (in configuration namespace), and
- + // probe output trace source ("OutputBytes") to plot. The fourth argument
- + // specifies the name of the data series label on the plot. The last
- + // argument formats the plot by specifying where the key should be placed.
- + plotHelper.PlotProbe (probeType,
- + tracePath,
- + "OutputBytes",
- + "Packet Byte Count",
- + GnuplotAggregator::KEY_BELOW);
+ + // for the output files generated. The second, third, and fourth
+ + // arguments are, respectively, the plot title, x-axis, and y-axis labels
+ + plotHelper.ConfigurePlot ("seventh-packet-byte-count",
+ + "Packet Byte Count vs. Time",
+ + "Time (Seconds)",
+ + "Packet Byte Count");
+ +
+ + // Specify the probe type, trace source path (in configuration namespace), and
+ + // probe output trace source ("OutputBytes") to plot. The fourth argument
+ + // specifies the name of the data series label on the plot.
+ + plotHelper.AddProbe (probeType,
+ + tracePath,
+ + "OutputBytes",
+ + "Packet Byte Count");
+
+ // Use FileHelper to write out the packet byte count over time
+ FileHelper fileHelper;
@@ -270,13 +268,11 @@
+ // Specify the probe type, trace source path (in configuration namespace), and
+ // probe output trace source ("OutputBytes") to plot. The fourth argument
- + // specifies the name of the data series label on the plot. The last
- + // argument formats the plot by specifying where the key should be placed.
- + plotHelper.PlotProbe (probeType,
- + tracePath,
- + "OutputBytes",
- + "Packet Byte Count",
- + GnuplotAggregator::KEY_BELOW);
+ + // specifies the name of the data series label on the plot.
+ + plotHelper.AddProbe (probeType,
+ + tracePath,
+ + "OutputBytes",
+ + "Packet Byte Count");
The first two arguments are the name of the probe type and the trace source path.
These two are probably the hardest to determine when you try to use
@@ -288,7 +284,8 @@
::
.AddTraceSource ("Tx", "Send IPv6 packet to outgoing interface.",
- MakeTraceSourceAccessor (&Ipv6L3Protocol::m_txTrace))
+ MakeTraceSourceAccessor (&Ipv6L3Protocol::m_txTrace),
+ "ns3::Ipv6L3Protocol::TxRxTracedCallback")
This says that ``Tx`` is a name for variable ``m_txTrace``, which has
a declaration of:
@@ -300,11 +297,32 @@
*/
TracedCallback<Ptr<const Packet>, Ptr<Ipv6>, uint32_t> m_txTrace;
+
+The last argument specifies that it is a TxRxTracedCallback; this
+documentation string allows the signature to be easily found using
+Doxygen. If we look at this signature in the same header file, we can
+see also:
+
+::
+
+ /**
+ * TracedCallback signature for packet transmission or reception events.
+ *
+ * \param [in] packet The packet.
+ * \param [in] ipv6
+ * \param [in] interface
+ */
+ typedef void (* TxRxTracedCallback)
+ (const Ptr<const Packet> packet, const Ptr<const Ipv6> ipv6,
+ const uint32_t interface);
+
+i.e. the same information about the arguments is present in this typedef.
+
It turns out that this specific trace source signature is supported
by a Probe class (what we need here) of class Ipv6PacketProbe.
See the files ``src/internet/model/ipv6-packet-probe.{h,cc}``.
-So, in the PlotProbe statement above, we see that the statement is
+So, in the AddProbe statement above, we see that the statement is
hooking the trace source (identified by path string) with a matching
|ns3| Probe type of ``Ipv6PacketProbe``. If we did not support
this probe type (matching trace source signature), we could have not
@@ -324,17 +342,20 @@
.SetGroupName ("Stats")
.AddConstructor<Ipv6PacketProbe> ()
.AddTraceSource ( "Output",
- "The packet plus its IPv6 object and interface that serve as the output for this probe",
- MakeTraceSourceAccessor (&Ipv6PacketProbe::m_output))
+ "The packet plus its IPv6 object and interface "
+ "that serve as the output for this probe",
+ MakeTraceSourceAccessor (&Ipv6PacketProbe::m_output),
+ "ns3::Ipv6PacketProbe::TracedCallback")
.AddTraceSource ( "OutputBytes",
"The number of bytes in the packet",
- MakeTraceSourceAccessor (&Ipv6PacketProbe::m_outputBytes))
+ MakeTraceSourceAccessor (&Ipv6PacketProbe::m_outputBytes),
+ "ns3::Packet::PacketSizeTracedCallback")
;
return tid;
}
-The third argument of our PlotProbe statement specifies that we are
+The third argument of our AddProbe statement specifies that we are
interested in the number of bytes in this packet; specifically, the
"OutputBytes" trace source of Ipv6PacketProbe.
Finally, the last two arguments of the statement provide the plot
@@ -343,6 +364,31 @@
the plot key to be inserted below the plot. Other options include
NO_KEY, KEY_INSIDE, and KEY_ABOVE.
+Multiple data series can be added to a single plot.
+This can be done by repeatedly calling ``AddProbe()`` such as in the
+previous example (avoiding the use of wildcards):
+
+::
+
+ tracePath = "/NodeList/0/$ns3::Ipv4L3Protocol/Tx";
+ plotHelper.AddProbe (probeType,
+ tracePath,
+ "OutputBytes",
+ "Packet Byte Count for node 0");
+ tracePath = "/NodeList/1/$ns3::Ipv4L3Protocol/Tx";
+ plotHelper.AddProbe (probeType,
+ tracePath,
+ "OutputBytes",
+ "Packet Byte Count for node 1");
+
+Finally, by default, the helper uses a Collector type of
+``ns3::EventDrivenCollector`` which does not do any processing
+of the data generated asynchronously by the trace sources. Other
+Collector types are possible, such as a TimeSeriesCollector to
+generate periodic time-series, a TimeAverageCollector to generate
+rates (such as data rate from an interface, sampled every second),
+and the ability to scale the Y-axis data using a ScalingCollector.
+More details can be found in the |ns3| manual.
Supported Trace Types
*********************

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b