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

Unified Diff: src/stats/doc/collector.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: src/stats/doc/collector.rst
===================================================================
--- a/src/stats/doc/collector.rst
+++ b/src/stats/doc/collector.rst
@@ -9,10 +9,57 @@
Collectors
**********
-This section is a placeholder to detail the functionalities provided by
-the Collector
-class to an |ns3| simulation, and gives examples on how to code them
-in a program.
+As stated in the introduction, a *Collector* consumes the data generated
+by one or more Probe objects. It performs transformations on the data,
+such as normalization, reduction, and the computation of basic statistics.
+Collector objects do not produce data that is directly output by the ns-3
+run; instead, they output data downstream to another type of object,
+called *Aggregator*, which performs that function. Typically,
+Collectors output their data in the form of trace sources as well,
+allowing collectors to be chained in series.
-**Note:** As of ns-3.18, Collectors are still under development and
-not yet provided as part of the framework.
+There are four Collector types presently provided:
+
+* EventDrivenCollector
+* TimeSeriesCollector
+* TimeAverageCollector
+* ScalingCollector
+
+There is a Collector base class that exists to provide default
+implementations of various TraceSinks for popular |ns3| data types
+(e.g. Double, Boolean, Time), and to allow for generic collector containers
+that hold different types of collectors.
+
+The ``ns3::EventDrivenCollector`` is almost a pass-through object
+for data generated by probes; its main responsibility is for converting
+output data into C++ type ``double``, and for appending a timestamp
+(also of type ``double``). The data is provided in a trace source
+named ``Output`` with signature:
+
+::
+
+ // the output data trace source
+ TracedCallback<double, double> m_output;
+
+In fact, this is a common pattern for trace sources from these collectors,
+converting current |ns3| Time to a double value (seconds) and converting
+the new value provided by the probe to a double valued quantity.
+
+The EventDrivenCollector provides output asynchronously, for each
+event generated by the attached probe. The ``ns3::TimeSeriesCollector``
+instead provides a time series of data, sampled every ``Period`` seconds
+(where Period is an |ns3| attribute). So while a probe may produce
+data many times per second, the time series collector outputs the most
+currently received value when its regular period is up.
+
+The ``ns3::TimeAverageCollector`` will also produce regular output according
+to a period (default 1 second), but will sum and average the values
+received by the probe across the measurement period. This is useful for
+plotting data rates (e.g. if a probe said that two 1000 byte packets
+were generated in the past second, the output of this collector would
+be 16,000 (bits/sec) in that reporting interval).
+
+Finally, the ``ns3::ScalingCollector`` will transform the input data
+that it receives by multiplying by a scaling factor, useful for
+converting the units on the output data. This collector is usually
+placed in series with another upstream Collector.

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