src/core/tracing.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Wed, 29 Aug 2007 16:43:19 +0200
changeset 1398 607b6e86e143
parent 1392 c73109c96c85
child 1407 853d1696aece
permissions -rw-r--r--
reference the proper trace source list group
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1398
607b6e86e143 reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1392
diff changeset
     1
/**
607b6e86e143 reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1392
diff changeset
     2
 * \defgroup TraceSourceList List of trace sources
607b6e86e143 reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1392
diff changeset
     3
 */
607b6e86e143 reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1392
diff changeset
     4
1391
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
     5
/**
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
     6
 * \defgroup tracing Tracing
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
     7
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
     8
 * The flexibility of the ns-3 tracing system comes at the cost of quite
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
     9
 * a bit of complexity so, before trying to use the low-level aspects
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    10
 * of the tracing API, it is important to focus on some basic definitions:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    11
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    12
 * - A trace source is an object instance which can report trace events
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    13
 *   to a set of listening trace sinks.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    14
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    15
 * - A trace sink is a user-provided callback (a function) which can
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    16
 *   be connected to a set of trace sources to receive the events generated
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    17
 *   by each trace source.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    18
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    19
 * - A trace resolver is an object which allows users to establish 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    20
 *   connections between a set of trace sources and a set of trace sinks.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    21
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    22
 * So, what does it look like in practice ? First, let's look at trace
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    23
 * sources. We have two types of trace sources: numeric, and, normal 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    24
 * trace sources. Numeric trace sources behave as normal c++ integers 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    25
 * or c++ floating point numbers except that they report as trace events 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    26
 * each change of their value. For example:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    27
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    28
 * class MyModel 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    29
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    30
 * public:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    31
 *   void DoSomething (void) 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    32
 *   {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    33
 *     // use the "int" trace source just 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    34
 *     // like any other "int" variable.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    35
 *     m_cwnd *= 2;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    36
 *     m_cwnd += 4;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    37
 *     if (m_cwnd > 100)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    38
 *       {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    39
 *         // do something.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    40
 *       }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    41
 *   }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    42
 * private:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    43
 *   // declare an instance of a "int" trace source
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    44
 *   SVTraceSource<int> m_cwnd;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    45
 * };
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    46
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    47
 * Normal trace sources, on the other hand, allow you to trace the
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    48
 * call of arbitrary functions and methods, as shown below. They are
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    49
 * typically used to track "rx", "tx", or "drop" events but could
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    50
 * also be used to track route change events, or position change
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    51
 * events:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    52
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    53
 * class MyModel 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    54
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    55
 * public:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    56
 *   void DoSomething (Packet packet, double value) 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    57
 *   {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    58
 *     m_doSomething (packet, value);
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    59
 *     // do something
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    60
 *   }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    61
 * private:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    62
 *   // report every "something" function call.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    63
 *   CallbackTraceSource<Packet,double> m_doSomething;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    64
 * };
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    65
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    66
 * Every type of trace source derives from the ns3::TraceSource base class.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    67
 * As of today, the set of concrete subclasses is relatively short:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    68
 * ns3::CallbackTraceSource, ns3::SvTraceSource, ns3::UvTraceSource, and,
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    69
 * ns3::FvTraceSource.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    70
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    71
 * To receive these trace events, a user should specify a set of trace sinks.
1392
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    72
 * For example, to receive the "int" and the "something" events shown in the
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    73
 * examples above, a user would declare the following functions:
1391
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    74
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    75
 * // oldValue and newValue contain the previous and new values of 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    76
 * // the connected SVTraceSource<int> trace source.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    77
 * void 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    78
 * CwndTraceSink (const TraceContext &context, int64_t oldValue, int64_t newValue)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    79
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    80
 *   // for example, print the new value:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    81
 *   std::cout << "cwnd=" << newValue << std::endl;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    82
 * }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    83
 * void 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    84
 * DoSomethingTraceSink (const TraceContext &context, Packet packet, double value)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    85
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    86
 *   // for example, print the arguments
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    87
 *   std::cout << "value=" << value << ", packet " << packet << std::endl;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    88
 * }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    89
 * \endcode
1392
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    90
 * Each of these sink function takes, as a first argument, a reference to a 
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    91
 * const TraceContext object. This context object contains information which
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    92
 * describes the instance of the connected trace source: that information is
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    93
 * setup during the connection process and does not change afterwards
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    94
 * The type and the number of the other arguments to each trace sink depends
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    95
 * on the type of the connected trace source: it conveys per-event information
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    96
 * from the trace source to the trace sink. For example, UVTraceSource and 
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    97
 * SVTraceSource trace sources require two extra arguments. The former requires
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
    98
 * two unsigned 64 bit integers while the latter requires two signed 64 bit 
1398
607b6e86e143 reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1392
diff changeset
    99
 * integers. More generally, users can consult the \ref TraceSourceList
1392
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
   100
 * to figure out the arguments which a trace sink is required to receive
c73109c96c85 add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1391
diff changeset
   101
 * for each trace source.
1391
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   102
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   103
 * The hard part of this tracing framework is the "connection" step: there is a point
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   104
 * in the simulation scenario where the user is expected to specify which trace sources
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   105
 * should be connected to which trace sinks. There are many ways to do this: the
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   106
 * users who want to could implement the "quick and dirty" way, that is, they could
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   107
 * write adhoc code to connect their trace sinks to the trace sources using the 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   108
 * TraceSource::AddCallback method. For example, they could patch their models to
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   109
 * the following:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   110
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   111
 * class MyModel 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   112
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   113
 * public:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   114
 *   void DoSomething (void) 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   115
 *   {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   116
 *     // ...
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   117
 *   }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   118
 *   SVTraceSource<int> *GetCwndTraceSource (void) const
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   119
 *   {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   120
 *     return &m_cwnd;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   121
 *   }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   122
 * private:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   123
 *   // declare an instance of a "int" trace source
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   124
 *   SVTraceSource<int> m_cwnd;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   125
 * };
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   126
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   127
 * And, then, call directly the GetCwndTraceSource method:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   128
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   129
 * CwndTraceSink (const TraceContext &context, int64_t oldValue, int64_t newValue)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   130
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   131
 *   // for example, print the new value:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   132
 *   std::cout << "cwnd=" << newValue << std::endl;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   133
 * }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   134
 * // create a model instance
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   135
 * MyModel *model = ...;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   136
 * SVTraceSource<int> *cwnd = model->GetCwndTraceSource ();
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   137
 * // connect the trace sink to the cwnd trace source of
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   138
 * // this model instance.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   139
 * cwnd->AddCallback (MakeCallback (&CwndTraceSink), 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   140
 *                    TraceContext ());
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   141
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   142
 * 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   143
 * The solution described above is simple to implement for a model
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   144
 * author but it is hard to extend and becomes quickly cumbersome
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   145
 * to use with complex models made of composite objects. TraceResolvers
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   146
 * deal with these problems and offer a simple API to connect large
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   147
 * sets of trace sources to a single sink (as is typical for simulations
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   148
 * where users want to receive the "ipv4 rx" events from all nodes).
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   149
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   150
 * The user-visible API to connect and disconnect trace sources to
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   151
 * and from trace sinks is quite small: ns3::Object::Connect
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   152
 * and ns3::Object::Disconnect both take a "namespace" regexp string
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   153
 * and a callback. The input callback is connected to each trace source
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   154
 * which matches the namespace regexp string. The format of the namespace
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   155
 * string depends on the set of models implemented by the simulator. 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   156
 * The following diagram shows a small part of the namespace exported
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   157
 * by the current version of the simulator:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   158
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   159
 * \image html namespace-2.png ns-3 namespace
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   160
 * 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   161
 * In this namespace, the "rx" trace source of the PointToPointNetdevice 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   162
 * index 0 within node index 3 is uniquely identified by the namespace
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   163
 * string "/nodes/3/devices/0/rx". It is also possible to match all
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   164
 * such "rx" trace sources with a single namespace string using 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   165
 * a limited form of regular expressions: "/nodes/3/devices/* /rx" 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   166
 * identifies the "rx" trace source within all NetDevices within node
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   167
 * index 3. Similarly, "/nodes/* /devices/* /rx" identifies the "rx"
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   168
 * trace source within all NetDevices within all nodes. It is thus
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   169
 * possible to connect a single trace sink to a set of matching trace
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   170
 * sources in a single operation:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   171
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   172
 * void DeviceRxSink (const TraceContext &context, const Packet &packet)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   173
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   174
 *   // context contains enough information to uniquely identify
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   175
 *   // the trace source instance.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   176
 *   std::cout << "context: \"" << context << "\"";
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   177
 *   // packet is the per-event information conveyed from the
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   178
 *   // trace source to the trace sink.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   179
 *   std:: cout << " packet: " << packet << std::endl;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   180
 * }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   181
 * NodeList::Connect ("/nodes/* /devices/* /rx", MakeCallback (&DeviceRxSink));
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   182
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   183
 * Which, at runtime, is going to generate output looking like this:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   184
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   185
 * context: "nodeid=2 device=0 dev-rx" packet: IPV4(tos 0x0 ttl 64 id 0 offset ...
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   186
 * context: "nodeid=1 device=0 dev-rx" packet: IPV4(tos 0x0 ttl 64 id 0 offset ...
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   187
 * ...
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   188
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   189
 * In the example above, we see that the ns3::TraceContext contains three 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   190
 * ns3::TraceContextElement which were printed using a space separator:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   191
 *  - nodeid=i
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   192
 *  - device=j
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   193
 *  - dev-rx
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   194
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   195
 * Of course, the user could also extract each of these elements from
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   196
 * the context to generate a different output:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   197
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   198
 * void DeviceRxSink (const TraceContext &context, const Packet &packet)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   199
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   200
 *   NodeListIndex nodeIndex;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   201
 *   NodeNetDeviceIndex deviceIndex;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   202
 *   context.Get (nodeIndex);
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   203
 *   context.Get (deviceIndex);
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   204
 *   std::cout << "node-index=" << nodeIndex.Get ();
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   205
 *   std::cout << ", device-index=" << deviceIndex.Get ();
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   206
 *   std::cout << ", packet: " << packet;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   207
 *   std::cout << std::endl;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   208
 * }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   209
 * NodeList::Connect ("/nodes/* /devices/* /rx", MakeCallback (&DeviceRxSink));
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   210
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   211
 * Extracting TraceContextElement objects from a TraceContext in this manner
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   212
 * raises a few obvious questions:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   213
 *   - how do I know which trace context elements are present in a given
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   214
 *     TraceContext ?
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   215
 *   - how are these elements added to the TraceContext ?
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   216
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   217
 * 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   218
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   219
 * 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   220
 * Connecting trace sinks to a set of existing trace sources is nice but
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   221
 * model developers also often need to be able to create new trace sources
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   222
 * and hook them into the namespace resolution system. Creating new trace
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   223
 * sources is pretty easy: it is a matter of instantiating a proper
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   224
 * subclass of the ns3::TraceSource base class. However, hooking each
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   225
 * new trace source in the overall namespace resolution system requires
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   226
 * some new effort. The core requirement is that the user needs to
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   227
 * subclass from the ns3::Object base class which provides the most
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   228
 * basic ns3::Object::Connect, and, ns3::Object::Disconnect methods.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   229
 * These two methods are simple forwarding methods to the virtual 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   230
 * ns3::Object::GetTraceResolver method which does the bulk of the work
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   231
 * required to setup properly trace sources.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   232
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   233
 * Every subclass of the ns3::Object base class which wishes to export
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   234
 * a set of trace sources and make them available through the Connect/Disconnect
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   235
 * functions needs to override the ns3::Object::GetTraceResolver method.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   236
 * This method needs to return a subclass of the ns3::TraceResolver
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   237
 * base class which implements the ns3::TraceResolver::Connect and
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   238
 * ns3::TraceResolver::Disconnect methods. Providing an implementation
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   239
 * of these two methods is a bit complicated so, a default implementation
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   240
 * named CompositeTraceResolver is provided:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   241
 * \code
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   242
 * class MyModel : public Object
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   243
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   244
 * public:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   245
 *   void DoSomething (void) 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   246
 *   {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   247
 *     // change value of m_cwnd
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   248
 *   }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   249
 * protected:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   250
 *   virtual Ptr<TraceResolver> GetTraceResolver (void)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   251
 *   {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   252
 *     // create the composite resolver
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   253
 *     Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> ();
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   254
 *     resolver->AddSource ("cwnd", m_cwnd);
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   255
 *     resolver->AddSource ("rx", m_rx);
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   256
 *     return resolver;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   257
 *   }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   258
 * private:
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   259
 *   SVTraceSource<int> m_cwnd;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   260
 *   CallbackTraceSource<Packet> m_rx;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   261
 * };
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   262
 * void MyTraceSink (const TraceContext &context, Packet packet)
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   263
 * {
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   264
 *   std::cout << context << " packet: " << packet << std::endl;
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   265
 * }
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   266
 * object->Connect ("/.../rx", MakeCallback (&MyTraceSink));
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   267
 * \endcode
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   268
 * 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   269
 * The above example is enough to export a trace source as a member of the
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   270
 * tracing namespace so, it would be enough to allow a user to perform a
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   271
 * pair of Connect/Disconnect operations but it would not be enough to allow
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   272
 * a TraceContext to contain information about these trace sources. Specifically, 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   273
 * printing the content of the TraceContext as shown above would give no 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   274
 * information whatsoever about the type of trace source which was connected.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   275
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   276
 * but it is not enough to allow the TraceContext
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   277
 * stored in each TraceSource to store information about these trace sources.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   278
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   279
 * - A trace source: a trace source is an object instance which is a 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   280
 *   subclass of the ns3::TraceSource base class. Each instance
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   281
 *   of a trace source should be used to report a single type of
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   282
 *   event. For example, if you want to report ipv4 rx and tx events, 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   283
 *   you should use two different trace source instances.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   284
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   285
 *   - Trace sinks: a trace sink is a callback, that is, a function,
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   286
 *     which is provided by the user of a model to receive the events
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   287
 *     reported by a set of trace sources within that model. A trace 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   288
 *     sink is said to be "connected" once it has been associated
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   289
 *     to a set of trace sources.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   290
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   291
 *   - Trace context: each trace source instance is associated with a single
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   292
 *     instance of an immutable trace context. Each ns3::TraceContext stores 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   293
 *     a set of trace context element instances, each of which is a subclass 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   294
 *     of the ns3::TraceContextElement base class. Whenever a trace sink
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   295
 *     provided by a user is called because a trace event was reported on
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   296
 *     a connected trace source, the trace context associated to the
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   297
 *     relevant trace source is passed as an extra argument to the user's
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   298
 *     trace sink.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   299
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   300
 *   - instrumentation of models is done through a set of trace source 
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   301
 *     instances, each of which is a subclass of the ns3::TraceSource
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   302
 *     base class.
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   303
 *
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   304
 *   
ce9ab2cbf936 add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
   305
 */