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. |