author | Tom Henderson <tomh@tomh.org> |
Thu, 10 Jan 2008 07:31:40 -0800 | |
changeset 2217 | 0b4567d545de |
parent 2202 | 42df2e81ae64 |
child 2594 | a8f89acd17a1 |
permissions | -rw-r--r-- |
1398
607b6e86e143
reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1392
diff
changeset
|
1 |
/** |
2217 | 2 |
* \ingroup core |
1398
607b6e86e143
reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1392
diff
changeset
|
3 |
* \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
|
4 |
*/ |
607b6e86e143
reference the proper trace source list group
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1392
diff
changeset
|
5 |
|
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
6 |
/** |
2217 | 7 |
* \ingroup core |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
8 |
* \defgroup tracing Tracing |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
9 |
* |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
10 |
* 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
|
11 |
* 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
|
12 |
* 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
|
13 |
* |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
14 |
* - 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
|
15 |
* to a set of listening trace sinks. |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
16 |
* |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
17 |
* - 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
|
18 |
* 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
|
19 |
* by each trace source. |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
20 |
* |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
21 |
* - 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
|
22 |
* 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
|
23 |
* |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
24 |
* \section TraceSource Generating Trace Events |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
25 |
* |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
26 |
* 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
|
27 |
* 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
|
28 |
* 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
|
29 |
* 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
|
30 |
* each change of their value. For example: |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
31 |
* \code |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
32 |
* class MyModel |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
33 |
* { |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
34 |
* public: |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
35 |
* void DoSomething (void) |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
36 |
* { |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
37 |
* // use the "int" trace source just |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
38 |
* // like any other "int" variable. |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
39 |
* m_cwnd *= 2; |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
40 |
* m_cwnd += 4; |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
41 |
* if (m_cwnd > 100) |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
42 |
* { |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
43 |
* // do something. |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
44 |
* } |
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 |
* private: |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
47 |
* // declare an instance of a "int" trace source |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
48 |
* SVTraceSource<int> m_cwnd; |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
49 |
* }; |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
50 |
* \endcode |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
51 |
* 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
|
52 |
* 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
|
53 |
* 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
|
54 |
* 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
|
55 |
* events: |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
56 |
* \code |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
57 |
* class MyModel |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
58 |
* { |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
59 |
* public: |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
60 |
* void DoSomething (Ptr<Packet> packet) |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
61 |
* { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
62 |
* // report this event on packet |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
63 |
* m_doSomething (packet); |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
64 |
* // do something |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
65 |
* } |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
66 |
* private: |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
67 |
* // report every "something" function call. |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
68 |
* CallbackTraceSource<Ptr<Packet> > m_doSomething; |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
69 |
* }; |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
70 |
* \endcode |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
71 |
* 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
|
72 |
* 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
|
73 |
* ns3::CallbackTraceSource, ns3::SvTraceSource, ns3::UvTraceSource, and, |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
74 |
* ns3::FvTraceSource. |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
75 |
* |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
76 |
* \section TraceSink Receiving Trace Events |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
77 |
* |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
78 |
* 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
|
79 |
* 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
|
80 |
* 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
|
81 |
* \code |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
82 |
* // 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
|
83 |
* // the connected SVTraceSource<int> trace source. |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
84 |
* void |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
85 |
* 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
|
86 |
* { |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
87 |
* // for example, print the new value: |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
88 |
* std::cout << "cwnd=" << newValue << std::endl; |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
89 |
* } |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
90 |
* void |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
91 |
* DoSomethingTraceSink (const TraceContext &context, Ptr<Packet> packet) |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
92 |
* { |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
93 |
* // for example, print the packet |
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
94 |
* std::cout << "packet " << packet->Print () << std::endl; |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
95 |
* } |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
96 |
* \endcode |
1392
c73109c96c85
add some text on trace sink signatures
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1391
diff
changeset
|
97 |
* 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
|
98 |
* 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
|
99 |
* 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
|
100 |
* 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
|
101 |
* 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
|
102 |
* 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
|
103 |
* 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
|
104 |
* 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
|
105 |
* 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
|
106 |
* 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
|
107 |
* to figure out the arguments which a trace sink is required to receive |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
108 |
* for each trace source: a signature of the user trace sink must match |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
109 |
* _exactly_ the signature documented in the \ref TraceSourceList. |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
110 |
* |
1415
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
111 |
* |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
112 |
* \section TraceSourceSimpleExport A simple way to connect Trace Sources with Trace Sinks |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
113 |
* |
1415
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
114 |
* The crux of the complexity of the ns-3 tracing system comes from its |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
115 |
* flexible system used to connect trace sources to trace sinks but what is really |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
116 |
* nice about it is that it is not necessary to use it to setup simple traces. |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
117 |
* |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
118 |
* The simplest way to export a set of trace sources to a user, for example, |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
119 |
* during the early prototyping phases of a system, is to add a set of public methods |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
120 |
* to give to your users access to the trace source object instances you use to generate |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
121 |
* trace events: |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
122 |
* \code |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
123 |
* class MyModel |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
124 |
* { |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
125 |
* public: |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
126 |
* void DoSomething (Ptr<Packet> packet) |
1415
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
127 |
* { |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
128 |
* // report this event on packet |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
129 |
* m_doSomething (packet); |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
130 |
* // do something |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
131 |
* } |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
132 |
* CallbackTraceSource<Ptr<Packet>> *PeekSomethingTraceSource (void) const |
1415
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
133 |
* { |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
134 |
* return &m_doSomething |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
135 |
* } |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
136 |
* private: |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
137 |
* // report every "something" function call. |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
138 |
* CallbackTraceSource<Ptr<Packet>> m_doSomething; |
1415
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
139 |
* }; |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
140 |
* \endcode |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
141 |
* If your users hold a pointer to an instance of MyModel, and if they want to connect |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
142 |
* a MySomethingSink, they can simply do the following which invokes the |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
143 |
* TraceSource::AddCallback method and creates a Callback object from the user's |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
144 |
* sink with the MakeCallback function. |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
145 |
* \code |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
146 |
* void |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
147 |
* MySomethingSink (const TraceContext &context, Ptr<Packet> packet) |
1415
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
148 |
* { |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
149 |
* // do whatever you want. |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
150 |
* } |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
151 |
* MyModel *model = ...; |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
152 |
* CallbackTraceSource<Ptr<Packet>> *source = model->PeekSomethingTraceSource (); |
1416
2daa908b1b33
fix a small typo
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1415
diff
changeset
|
153 |
* source->AddCallback (MakeCallback (&MySomethingSink)); |
1415
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
154 |
* \endcode |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
155 |
* |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
156 |
* The full power of the tracing system comes however from its ns3::NodeList::Connect |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
157 |
* method which is described in the following sections. |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
158 |
* |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
159 |
* \section TraceConnection Connecting Trace Sources to Trace Sinks |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
160 |
* |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
161 |
* If a trace source is integrated in the ns-3 trace connection facility, a user |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
162 |
* should call the ns3::NodeList::Connect method to establish a connection between |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
163 |
* a trace sink and a set of matching trace sources. The second argument to that |
ac1df67308e6
add missing section on simple trace connection
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1413
diff
changeset
|
164 |
* method is a callback to the user's trace sink. |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
165 |
* That callback is easy to construct: call ns3::MakeCallback and you are done. The |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
166 |
* first argument is a string whose format is similar to a unix path and which is |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
167 |
* used to uniquely identify the set of trace sources you want to connect to. |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
168 |
* The set of acceptable path strings is also documented in the \ref TraceSourceList. |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
169 |
* |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
170 |
* So, what does this look like from the perspective of a user ? If we wanted to |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
171 |
* connect to a trace source defined somewhere deep into the a set of NetDevice objects |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
172 |
* located in some nodes of the system, we could write the following: |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
173 |
* \code |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
174 |
* void |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
175 |
* DoSomethingTraceSink (const TraceContext &context, Ptr<Packet> packet) |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
176 |
* { |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
177 |
* // for example, print the packet |
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
178 |
* std::cout << "packet: " << packet->Print () << std::endl; |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
179 |
* } |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
180 |
* // connect the above sink to a matching trace source |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
181 |
* NodeList::Connect ("/nodes/* /devices/* /rx", MakeCallback (&DoSomethingTraceSink)); |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
182 |
* \endcode |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
183 |
* |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
184 |
* The connection path string "/nodes/* /devices/* /rx" matches the "rx" trace source |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
185 |
* located in every netdevice located in every node. The syntax of that path string |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
186 |
* is loosely based on regular expressions so, a user could conceivably connect |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
187 |
* to the trace sources present in only one node identified by node index: |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
188 |
* "/nodex/3/devices/* /rx". |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
189 |
* |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
190 |
* The matching algorithm used here is very useful since it allows you to connect |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
191 |
* at once a large set of trace sources to a single sink but it introduces another |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
192 |
* problem: it becomes impossible when you receive an event in your trace sink to |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
193 |
* know from _which_ trace source the event is coming from. In our example, the |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
194 |
* trace source might be coming from the NetDevice number 2 of Node 10 or Netdevice |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
195 |
* number 0 of Node 5. In both cases, you might need to know which of these NetDevice |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
196 |
* is generating this event, if only to generate some ascii trace dump. Another |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
197 |
* similar use-case is that you might have connected the same trace sink to |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
198 |
* multiple types of events which have the same signature: it is quite common |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
199 |
* to receive all tx, rx, and drop events in the same trace sink and that would be |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
200 |
* quite trivial to achieve with a string such as: "/nodes/* /devices/* /*" |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
201 |
* |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
202 |
* The source of a trace event can be retrieved from a trace sink using |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
203 |
* different means: the simplest |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
204 |
* way to get this information is to use the builtin printing facility of |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
205 |
* the TraceContext object: |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
206 |
* \code |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
207 |
* void |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
208 |
* DoSomethingTraceSink (const TraceContext &context, Ptr<Packet> packet) |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
209 |
* { |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
210 |
* // for example, print the packet |
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
211 |
* std::cout << "context=\"" << context << "\" packet: " << packet->Print () << std::endl; |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
212 |
* } |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
213 |
* \endcode |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
214 |
* The above code is going to generate output which looks like the following: |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
215 |
* \code |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
216 |
* context="nodeid=2 device=0 dev-rx" packet: IPV4(tos 0x0 ttl 64 id 0 offset ... |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
217 |
* context="nodeid=1 device=0 dev-rx" packet: IPV4(tos 0x0 ttl 64 id 0 offset ... |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
218 |
* ... |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
219 |
* \endcode |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
220 |
* |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
221 |
* Another more advanced way to get information out of a TraceContext is to call its |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
222 |
* ns3::TraceContext::GetElement method. This method takes as its first and only |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
223 |
* argument an instance of the object we want to read and the list of available |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
224 |
* object instances we can read from a TraceContext is documented, once again, |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
225 |
* in the \ref TraceSourceList. For example, we could write the following to |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
226 |
* generate adhoc trace output: |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
227 |
* \code |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
228 |
* void DeviceRxSink (const TraceContext &context, Ptr<const Packet> packet) |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
229 |
* { |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
230 |
* NodeListIndex nodeIndex; |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
231 |
* NodeNetDeviceIndex deviceIndex; |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
232 |
* context.GetElement (nodeIndex); |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
233 |
* context.GetElement (deviceIndex); |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
234 |
* std::cout << "node-index=" << nodeIndex.Get (); |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
235 |
* std::cout << ", device-index=" << deviceIndex.Get (); |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
236 |
* std::cout << ", packet: " << packet->Print (); |
1407
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
237 |
* std::cout << std::endl; |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
238 |
* } |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
239 |
* \endcode |
853d1696aece
add section on TraceContexts in tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1398
diff
changeset
|
240 |
* |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
241 |
* \section ExportingTraceSources Exporting new Trace Sources |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
242 |
* |
1408
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
243 |
* Using existing trace sources to connect them to a set of adhoc trace sinks |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
244 |
* is not really complicated but, setting up new trace sources which can hook |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
245 |
* in this automatic connection system is a bit more complicated. |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
246 |
* |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
247 |
* So far, we know that a model author can generate trace events really easily: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
248 |
* \code |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
249 |
* class MyModel |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
250 |
* { |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
251 |
* public: |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
252 |
* void DoSomething (Ptr<Packet> packet) |
1408
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
253 |
* { |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
254 |
* // report this event on packet with value |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
255 |
* m_doSomething (packet); |
1408
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
256 |
* // do something |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
257 |
* } |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
258 |
* private: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
259 |
* // report every "something" function call. |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
260 |
* CallbackTraceSource<Ptr<Packet>> m_doSomething; |
1408
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
261 |
* }; |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
262 |
* \endcode |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
263 |
* |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
264 |
* To make these new trace sources available to the rest of the connection system, |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
265 |
* the first step is to make sure that your model object derives from the ns3::Object |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
266 |
* base class either directly (as shown below) or indirectly through another base class: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
267 |
* \code |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
268 |
* class MyModel : public Object {...}; |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
269 |
* // or: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
270 |
* class SomeOtherObject : public Object {...}; |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
271 |
* class MyModel : public SomeOtherObject {...}; |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
272 |
* \endcode |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
273 |
* |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
274 |
* This is pretty trivial and lays the ground for the second step: overriding the |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
275 |
* ns3::Object::GetTraceResolver method: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
276 |
* \code |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
277 |
* class MyModel : public MyParent |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
278 |
* { |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
279 |
* public: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
280 |
* // declare overriden method |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
281 |
* virtual Ptr<TraceResolver> GetTraceResolver (void) const; |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
282 |
* private: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
283 |
* // the new trace source to export. |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
284 |
* CallbackTraceSource<Ptr<Packet>> m_rxSource; |
1408
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
285 |
* }; |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
286 |
* \endcode |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
287 |
* |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
288 |
* To implement this method, you could attempt to implement a new subclass of |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
289 |
* the ns3::TraceResolver base class and return an instance from this method but |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
290 |
* this would be very hard. Instead, you should use the helper class |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
291 |
* ns3::CompositeTraceResolver to register your trace sources and chain up to |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
292 |
* your parent: |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
293 |
* \code |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
294 |
* Ptr<TraceResolver> |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
295 |
* MyModel::GetTraceResolver (void) const |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
296 |
* { |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
297 |
* // create an empty trace resolver |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
298 |
* Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> (); |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
299 |
* // register m_rxSource |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
300 |
* resolver->AddSource ("rx", // the name of the trace source in the path string |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
301 |
* TraceDoc ("some help text to explain the purpose of this trace source", |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
302 |
* "Packet", // the type of the first argument to the trace source |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
303 |
* "the purpose of the first argument", |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
304 |
* "type-of-second-argument", "purpose-of-second-argument"), |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
305 |
* m_rxSource // the trace source itself is registered |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
306 |
* ); |
1408
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
307 |
* // make sure we include the trace sources implemented in the parent. |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
308 |
* resolver->SetParentResolver (MyParent::GetTraceResolver ()); |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
309 |
* return resolver; |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
310 |
* } |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
311 |
* \endcode |
3ddff4d9b27c
start section on registering new TraceSource objects
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1407
diff
changeset
|
312 |
* |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
313 |
* Once you have written that code, you must make sure that this new method GetTraceResolver |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
314 |
* is going to be called at some point by the tracing system. If your model is located somewhere |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
315 |
* deep in MAC or PHY layer, that is, it is part of a NetDevice implementation, all you |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
316 |
* have to do is to make sure that your model is registered as a "composite" of your NetDevice |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
317 |
* subclass: |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
318 |
* \code |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
319 |
* class MyNetDevice : public NetDevice |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
320 |
* { |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
321 |
* public: |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
322 |
* Ptr<TraceResolver> GetTraceResolver (void) const; |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
323 |
* private: |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
324 |
* Ptr<MyModel> m_model; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
325 |
* }; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
326 |
* |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
327 |
* Ptr<TraceResolver> |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
328 |
* MyNetDevice::GetTraceResolver (void) const |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
329 |
* { |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
330 |
* Ptr<CompositeTraceResolver> resolver = ...; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
331 |
* // register other trace source |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
332 |
* ... |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
333 |
* // register now your model as a "composite" |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
334 |
* resolver->AddComposite ("my-model", m_model); |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
335 |
* // chain up to parent. |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
336 |
* resolver->SetParentResolver (NetDevice::GetTraceResolver ()); |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
337 |
* return resolver; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
338 |
* } |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
339 |
* \endcode |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
340 |
* |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
341 |
* The code above will make your "rx" trace source appear under the |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
342 |
* /nodes/xx/devices/xx/my-model/rx namespace path. |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
343 |
* |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
344 |
* If you have implemented a new layer 3 or 4 protocol object, the process to |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
345 |
* export your trace sources is quite similar. You need to subclass from |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
346 |
* ns3::Object, override the ns3::Object::GetTraceResolver method, make |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
347 |
* sure you chain up to your parent's GetTraceResolver method, and, finally, |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
348 |
* make sure that someone calls your new GetTraceResolver method. How to accomplish |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
349 |
* the latter should be documented in the node's API documentation which describes |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
350 |
* how to implement a new layer 3 or 4 protocol object. |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
351 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
352 |
* \section AdvancedTraceContext Creating new Trace Context Elements |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
353 |
* |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
354 |
* The last important feature which model developers need to understand |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
355 |
* is how to provide extra context information to trace sinks. For example, |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
356 |
* if your model exports both rx and tx trace sources which share the same |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
357 |
* signature, it is quite natural for a user to connect to a single trace sink |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
358 |
* to both of them with a trace path string such as "/nodes/* /devices/* /(rx|tx)". |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
359 |
* In this case, it becomes necessary to be able, from the trace sink function, |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
360 |
* to tell which event triggered the call to the trace sink: a rx or a tx event. |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
361 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
362 |
* That example is detailed below with a TX, a RX, and a DROP source: |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
363 |
* \code |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
364 |
* class MyModel |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
365 |
* { |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
366 |
* private: |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
367 |
* CallbackTraceSource<Ptr<Packet>> m_rxSource; |
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
368 |
* CallbackTraceSource<Ptr<Packet>> m_txSource; |
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
369 |
* CallbackTraceSource<Ptr<Packet>> m_dropSource; |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
370 |
* }; |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
371 |
* \endcode |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
372 |
* When a single sink is connected to all 3 sources here, one might want |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
373 |
* to write code like the following: |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
374 |
* \code |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
375 |
* void DeviceRxSink (const TraceContext &context, Ptr<const Packet> &packet) |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
376 |
* { |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
377 |
* switch (type) { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
378 |
* case RX: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
379 |
* std::cout << "rx" << std::endl; |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
380 |
* break; |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
381 |
* case TX: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
382 |
* std::cout << "tx" << std::endl; |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
383 |
* break; |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
384 |
* case DROP: |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
385 |
* std::cout << "drop" << std::endl; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
386 |
* break; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
387 |
* } |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
388 |
* \endcode |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
389 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
390 |
* \subsection AdvancedTraceContextSimpleSolution The simple solution |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
391 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
392 |
* The simplest way to do achieve the result shown above is to include |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
393 |
* in the trace source an extra explicit argument which describes the source event: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
394 |
* - define a small enum with 3 values |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
395 |
* - change the signature of m_rxSource, m_txSource, and m_dropSource to include |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
396 |
* the enum |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
397 |
* - pass the enum value in each event |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
398 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
399 |
* The resulting code is shown below: |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
400 |
* \code |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
401 |
* class MyModel |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
402 |
* { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
403 |
* public: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
404 |
* // define the trace type enum. |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
405 |
* enum TraceType { |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
406 |
* RX, |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
407 |
* TX, |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
408 |
* DROP |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
409 |
* }; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
410 |
* private: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
411 |
* // generate events |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
412 |
* void NotifyRxPacket (Ptr<Packet> p) { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
413 |
* m_rxSource (p, MyModel::RX); |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
414 |
* } |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
415 |
* void NotifyTxPacket (Ptr<Packet> p) { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
416 |
* m_rxSource (p, MyModel::TX); |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
417 |
* } |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
418 |
* void NotifyDropPacket (Ptr<Packet> p) { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
419 |
* m_rxSource (p, MyModel::DROP); |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
420 |
* } |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
421 |
* CallbackTraceSource<Ptr<Packet>,enum TraceType> m_rxSource; |
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
422 |
* CallbackTraceSource<Ptr<Packet>,enum TraceType> m_txSource; |
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
423 |
* CallbackTraceSource<Ptr<Packet>,enum TraceType> m_dropSource; |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
424 |
* }; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
425 |
* \endcode |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
426 |
* These 3 new sources can be connected easily to a new trace sink: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
427 |
* \code |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
428 |
* void ASimpleTraceSink (const TraceContext &context, Ptr<const Packet> packet, enum MyModel::TraceType type) |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
429 |
* { |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
430 |
* // here, read the "type" argument |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
431 |
* } |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
432 |
* \endcode |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
433 |
* |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
434 |
* This solution works but it makes it impossible to connect a single trace sink to a set |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
435 |
* of trace sources which represent "rx" events in different NetDevice objects since |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
436 |
* each of them will define a different enum type with different values: since the |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
437 |
* trace sink signature must match exactly the trace source signature, it is impossible |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
438 |
* to connect at the same time to all "rx" events of different NetDevice. |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
439 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
440 |
* \subsection AdvancedTraceContextFancySolution The more complex and generic solution |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
441 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
442 |
* There is, hopefully, a way to get the best of both worlds, that is, to allow a |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
443 |
* user to connect to a lot of trace source events of the same kind but coming from different |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
444 |
* implementations and to allow the user to differentiate between these different |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
445 |
* implementations. |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
446 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
447 |
* Rather than define an adhoc enum type with a list of trace sources, you can also |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
448 |
* define a new ns3::TraceContextElement for your source sources. For example, if you |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
449 |
* define a new MyModelTraceType class which contains the type of trace, your users can |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
450 |
* then write trace sink code which looks like this: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
451 |
* \code |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
452 |
* void AFancyTraceSink (const TraceContext &context, Ptr<const Packet> packet) |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
453 |
* { |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
454 |
* MyModelTraceType type; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
455 |
* if (context.GetElement (type)) |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
456 |
* { |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
457 |
* switch (type.Get ()) |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
458 |
* { |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
459 |
* case MyModelTraceType::RX: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
460 |
* std::cout << "rx" << std::endl; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
461 |
* break; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
462 |
* case MyModelTraceType::TX: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
463 |
* std::cout << "tx" << std::endl; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
464 |
* break; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
465 |
* case MyModelTraceType::DROP: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
466 |
* std::cout << "drop" << std::endl; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
467 |
* break; |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
468 |
* } |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
469 |
* } |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
470 |
* } |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
471 |
* \endcode |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
472 |
* |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
473 |
* Of course, since the type of trace is stored in the TraceContext, your users can |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
474 |
* also take the shortcut which uses the printing functionality of the TraceContext: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
475 |
* \code |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
476 |
* void ALessFancyTraceSink (const TraceContext &context, Ptr<const Packet> packet) |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
477 |
* { |
2202
42df2e81ae64
update doc/tracing.h to Ptr<Packet>
Tom Henderson <tomh@tomh.org>
parents:
1810
diff
changeset
|
478 |
* std::cout << "context=\"" << context << "\" packet: " << packet->Print () << std::endl; |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
479 |
* } |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
480 |
* \endcode |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
481 |
* which will generate something like the following when the trace source comes |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
482 |
* from MyModel: |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
483 |
* \code |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
484 |
* context="my-model-rx" packet: ... |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
485 |
* \endcode |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
486 |
* |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
487 |
* The first step to achieve this is to define and implement a new |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
488 |
* subclass of the ns3::TraceContextElement base class. The exact list of |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
489 |
* public methods which must be implemented is described in the API |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
490 |
* documentation of the ns3::TraceContextElement class. |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
491 |
* \code |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
492 |
* class MyModelTraceType : public TraceContextElement |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
493 |
* { |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
494 |
* public: |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
495 |
* enum Type { |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
496 |
* RX, |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
497 |
* TX, |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
498 |
* DROP |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
499 |
* }; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
500 |
* // called from MyModel::GetTraceResolver |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
501 |
* MyModelTraceType (enum Type type); |
1810
06b88eac666b
add missing default constructor
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1809
diff
changeset
|
502 |
* // needed for by the tracing subsystem. |
06b88eac666b
add missing default constructor
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1809
diff
changeset
|
503 |
* MyModelTraceType (); |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
504 |
* // called from trace sink |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
505 |
* enum Type Get (void) const; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
506 |
* // needed by the tracing subsystem |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
507 |
* static uint16_t GetUid (void); |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
508 |
* // needed by the tracing subsystem to |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
509 |
* // print the content of a TraceContext |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
510 |
* void Print (std::ostream &os) const; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
511 |
* // needed by the tracing subsystem to |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
512 |
* // generate the doxygen documentation. |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
513 |
* std::string GetTypeName (void) const; |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
514 |
* private: |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
515 |
* enum Type m_type; |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
516 |
* }; |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
517 |
* \endcode |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
518 |
* The implementation does not require much thinking: |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
519 |
* \code |
1810
06b88eac666b
add missing default constructor
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1809
diff
changeset
|
520 |
* MyModelTraceType::MyModelTraceType () |
06b88eac666b
add missing default constructor
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1809
diff
changeset
|
521 |
* : m_type (RX) |
06b88eac666b
add missing default constructor
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1809
diff
changeset
|
522 |
* {// an arbitrary default value. |
06b88eac666b
add missing default constructor
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1809
diff
changeset
|
523 |
* } |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
524 |
* MyModelTraceType::MyModelTraceType (enum Type type) |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
525 |
* : m_type (type) |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
526 |
* {} |
1809
f429691996cc
add missing type specifier in sample code
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1807
diff
changeset
|
527 |
* enum MyModelTraceType::Type |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
528 |
* MyModelTraceType::Get (void) const |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
529 |
* { |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
530 |
* return m_type; |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
531 |
* } |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
532 |
* uint16_t |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
533 |
* MyModelTraceType::GetUid (void) |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
534 |
* { |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
535 |
* // use protected TraceContextElement::AllocateUid method |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
536 |
* // the input string is used to uniquely identify this new subclass |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
537 |
* static uint16_t uid = AllocateUid<MyModelTraceType> ("ns3::MyModelTraceType"); |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
538 |
* return uid; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
539 |
* } |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
540 |
* void |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
541 |
* MyModelTraceType::Print (std::ostream &os) const |
1807 | 542 |
* { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
543 |
* // this method is invoked by the print function of a TraceContext |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
544 |
* // if it contains an instance of this TraceContextElement. |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
545 |
* switch (m_type) { |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
546 |
* case RX: os << "rx"; break; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
547 |
* // ... |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
548 |
* } |
1807 | 549 |
* } |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
550 |
* std::string |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
551 |
* MyModelTraceType::GetTypeName (void) const |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
552 |
* { |
1413
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
553 |
* // This method should return a fully-qualified c++ typename |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
554 |
* // This method is used only for documentation purposes to |
a84b1ece69a2
re-organize the tutorial and use sections
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1411
diff
changeset
|
555 |
* // generate the content of the Trace Source List. |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
556 |
* return "ns3::MyModelTraceType"; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
557 |
* } |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
558 |
* \endcode |
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
559 |
* |
1410
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
560 |
* Once this subclass is implemented, the work is almost completed: you |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
561 |
* just need to pass an instance of that class as the last argument of |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
562 |
* the ns3::CompositeTraceResolver::AddSource method as shown below: |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
563 |
* \code |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
564 |
* Ptr<TraceResolver> |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
565 |
* MyModel::GetTraceResolver (void) const |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
566 |
* { |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
567 |
* // create an empty trace resolver |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
568 |
* Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> (); |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
569 |
* // register m_rxSource |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
570 |
* resolver->AddSource ("rx", // the name of the trace source in the path string |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
571 |
* TraceDoc ("some help text to explain the purpose of this trace source", |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
572 |
* "Packet", // the type of the first argument to the trace source |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
573 |
* "the purpose of the first argument", |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
574 |
* "type-of-second-argument", "purpose-of-second-argument"), |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
575 |
* m_rxSource, // the trace source itself is registered |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
576 |
* // the TraceContextElement associated to this trace source. |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
577 |
* MyModelTraceType (MyModelTraceType::RX) |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
578 |
* ); |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
579 |
* // make sure we include the trace sources implemented in the parent. |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
580 |
* resolver->SetParentResolver (MyParent::GetTraceResolver ()); |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
581 |
* return resolver; |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
582 |
* } |
70cc59001a4d
finish trace tutorial
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
1408
diff
changeset
|
583 |
* \endcode |
1391
ce9ab2cbf936
add some tracing documentation
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
584 |
*/ |