A Discrete-Event Network Simulator
API
time-probe-example.cc
Go to the documentation of this file.
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3  * Copyright (c) 2014 University of Washington
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License version 2 as
7  * published by the Free Software Foundation;
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  */
18 
19 //
20 // This example is designed to show the main features of an ns3::TimeProbe.
21 // A test object is used to emit values through a trace source. The
22 // example shows three ways to use a ns3::TimeProbe to hook the output
23 // of this trace source (in addition to hooking the raw trace source).
24 //
25 // It produces two types of output. By default, it will generate a
26 // gnuplot of interarrival times. If the '--verbose=1' argument is passed,
27 // it will also generate debugging output of the form (for example):
28 //
29 // Emitting at 96.5378 seconds
30 // context: raw trace source old 0.293343 new 0.00760254
31 // context: probe1 old 0.293343 new 0.00760254
32 // context: probe2 old 0.293343 new 0.00760254
33 // context: probe3 old 0.293343 new 0.00760254
34 //
35 // The stopTime defaults to 100 seconds but can be changed by an argument.
36 //
37 
38 #include <string>
39 
40 #include "ns3/core-module.h"
41 #include "ns3/time-probe.h"
42 #include "ns3/gnuplot-helper.h"
43 
44 using namespace ns3;
45 
46 NS_LOG_COMPONENT_DEFINE ("TimeProbeExample");
47 
53 class Emitter : public Object
54 {
55 public:
60  static TypeId GetTypeId (void);
61  Emitter ();
62 private:
63  void DoInitialize (void);
65  void Emit (void);
66 
70 };
71 
73 
74 TypeId
75 Emitter::GetTypeId (void)
76 {
77  static TypeId tid = TypeId ("ns3::Emitter")
78  .SetParent<Object> ()
79  .SetGroupName ("Stats")
80  .AddConstructor<Emitter> ()
81  .AddTraceSource ("Interval",
82  "Trace source",
84  "ns3::TracedValueCallback::Time")
85  ;
86  return tid;
87 }
88 
89 Emitter::Emitter (void)
90  : m_interval (Seconds (0)),
91  m_last (Seconds (0))
92 {
93  m_var = CreateObject<ExponentialRandomVariable> ();
94 }
95 
96 void
98 {
99  Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Emit, this);
100 }
101 
102 void
103 Emitter::Emit (void)
104 {
105  NS_LOG_DEBUG ("Emitting at " << Simulator::Now ().As (Time::S));
107  m_last = Simulator::Now ();
108  TimeProbe::SetValueByPath ("/Names/probe3", m_interval);
109  Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Emit, this);
110 }
111 
112 // This is a function to test hooking a raw function to the trace source
113 void
114 NotifyViaTraceSource (std::string context, Time oldVal, Time newVal)
115 {
117  GlobalValue::GetValueByName ("verbose", verbose);
118  if (verbose.Get ())
119  {
120  std::cout << "context: " << context << " old " << oldVal.As (Time::S) << " new " << newVal.As (Time::S) << std::endl;
121  }
122 }
123 
124 // This is a function to test hooking it to the probe output
125 void
126 NotifyViaProbe (std::string context, double oldVal, double newVal)
127 {
129  GlobalValue::GetValueByName ("verbose", verbose);
130  if (verbose.Get ())
131  {
132  std::cout << "context: " << context << " old " << oldVal << " new " << newVal << std::endl;
133  }
134 }
135 
136 static ns3::GlobalValue g_verbose ("verbose",
137  "Whether to enable verbose output",
138  ns3::BooleanValue (false),
140 
141 int main (int argc, char *argv[])
142 {
143  double stopTime = 100.0;
144  bool verbose = false;
145 
146  CommandLine cmd (__FILE__);
147  cmd.AddValue ("stopTime", "Time (seconds) to terminate simulation", stopTime);
148  cmd.AddValue ("verbose", "Whether to enable verbose output", verbose);
149  cmd.Parse (argc, argv);
150  bool connected;
151 
152  // Set a global value, so that the callbacks can access it
153  if (verbose)
154  {
155  GlobalValue::Bind ("verbose", BooleanValue (true));
156  LogComponentEnable ("TimeProbeExample", LOG_LEVEL_ALL);
157  }
158 
159  Ptr<Emitter> emitter = CreateObject<Emitter> ();
160  Names::Add ("/Names/Emitter", emitter);
161 
162  //
163  // The below shows typical functionality without a probe
164  // (connect a sink function to a trace source)
165  //
166  connected = emitter->TraceConnect ("Interval", "raw trace source", MakeCallback (&NotifyViaTraceSource));
167  NS_ASSERT_MSG (connected, "Trace source not connected");
168 
169  //
170  // Next, we'll show several use cases of using a Probe to access and
171  // filter the values of the underlying trace source
172  //
173 
174  //
175  // Probe1 will be hooked directly to the Emitter trace source object
176  //
177 
178  // probe1 will be hooked to the Emitter trace source
179  Ptr<TimeProbe> probe1 = CreateObject<TimeProbe> ();
180  // the probe's name can serve as its context in the tracing
181  probe1->SetName ("probe1");
182 
183  // Connect the probe to the emitter's Interval
184  connected = probe1->ConnectByObject ("Interval", emitter);
185  NS_ASSERT_MSG (connected, "Trace source not connected to probe1");
186 
187  // The probe itself should generate output. The context that we provide
188  // to this probe (in this case, the probe name) will help to disambiguate
189  // the source of the trace
190  connected = probe1->TraceConnect ("Output", probe1->GetName (), MakeCallback (&NotifyViaProbe));
191  NS_ASSERT_MSG (connected, "Trace source not connected to probe1 Output");
192 
193  //
194  // Probe2 will be hooked to the Emitter trace source object by
195  // accessing it by path name in the Config database
196  //
197 
198  // Create another similar probe; this will hook up via a Config path
199  Ptr<TimeProbe> probe2 = CreateObject<TimeProbe> ();
200  probe2->SetName ("probe2");
201 
202  // Note, no return value is checked here
203  probe2->ConnectByPath ("/Names/Emitter/Interval");
204 
205  // The probe itself should generate output. The context that we provide
206  // to this probe (in this case, the probe name) will help to disambiguate
207  // the source of the trace
208  connected = probe2->TraceConnect ("Output", "probe2", MakeCallback (&NotifyViaProbe));
209  NS_ASSERT_MSG (connected, "Trace source not connected to probe2 Output");
210 
211  //
212  // Probe3 will be called by the emitter directly through the
213  // static method SetValueByPath().
214  //
215  Ptr<TimeProbe> probe3 = CreateObject<TimeProbe> ();
216  probe3->SetName ("probe3");
217 
218  // By adding to the config database, we can access it later
219  Names::Add ("/Names/probe3", probe3);
220 
221  // The probe itself should generate output. The context that we provide
222  // to this probe (in this case, the probe name) will help to disambiguate
223  // the source of the trace
224  connected = probe3->TraceConnect ("Output", "probe3", MakeCallback (&NotifyViaProbe));
225  NS_ASSERT_MSG (connected, "Trace source not connected to probe3 Output");
226 
227  // Plot the interval values
228  GnuplotHelper plotHelper;
229  plotHelper.ConfigurePlot ("time-probe-example",
230  "Emitter interarrivals vs. Time",
231  "Simulation time (Seconds)",
232  "Interarrival time (Seconds)",
233  "png");
234 
235  // Helper creates a TimeProbe and hooks it to the /Names/Emitter/Interval
236  // source. Helper also takes the Output of the TimeProbe and plots it
237  // as a dataset labeled 'Emitter Interarrival Time'
238  plotHelper.PlotProbe ("ns3::TimeProbe",
239  "/Names/Emitter/Interval",
240  "Output",
241  "Emitter Interarrival Time",
242  GnuplotAggregator::KEY_INSIDE);
243 
244  // The Emitter object is not associated with an ns-3 node, so
245  // it won't get started automatically, so we need to do this ourselves
246  Simulator::Schedule (Seconds (0.0), &Emitter::Initialize, emitter);
247 
248  Simulator::Stop (Seconds (stopTime));
249  Simulator::Run ();
250  Simulator::Destroy ();
251 
252  return 0;
253 }
This is our test object, an object that increments counters at various times and emits one of them as...
static TypeId GetTypeId(void)
Register this type.
Time m_last
Current interarrival time.
void Emit(void)
Generate data.
TracedValue< Time > m_interval
Interarrival time between events.
void DoInitialize(void)
Initialize() implementation.
Ptr< ExponentialRandomVariable > m_var
Random number generator.
static TypeId GetTypeId(void)
Register this type.
AttributeValue implementation for Boolean.
Definition: boolean.h:37
Parse command-line arguments.
Definition: command-line.h:229
double GetValue(double mean, double bound)
Get the next random value, as a double from the exponential distribution with the specified mean and ...
Hold a so-called 'global value'.
Definition: global-value.h:74
Helper class used to make gnuplot plots.
void ConfigurePlot(const std::string &outputFileNameWithoutExtension, const std::string &title, const std::string &xLegend, const std::string &yLegend, const std::string &terminalType="png")
void PlotProbe(const std::string &typeId, const std::string &path, const std::string &probeTraceSource, const std::string &title, enum GnuplotAggregator::KeyLocation keyLocation=GnuplotAggregator::KEY_INSIDE)
A base class which provides memory management and object aggregation.
Definition: object.h:88
void Initialize(void)
Invoke DoInitialize on all Objects aggregated to this one.
Definition: object.cc:183
Simulation virtual time values and global simulation resolution.
Definition: nstime.h:103
TimeWithUnit As(const enum Unit unit=Time::AUTO) const
Attach a unit to a Time, to facilitate output in a specific unit.
Definition: time.cc:418
a unique identifier for an interface.
Definition: type-id.h:59
TypeId SetParent(TypeId tid)
Set the parent TypeId.
Definition: type-id.cc:922
Time stopTime
#define NS_ASSERT_MSG(condition, message)
At runtime, in debugging builds, if this condition is not true, the program prints the message to out...
Definition: assert.h:88
Ptr< const AttributeChecker > MakeBooleanChecker(void)
Definition: boolean.cc:121
#define NS_LOG_COMPONENT_DEFINE(name)
Define a Log component with a specific name.
Definition: log.h:205
#define NS_LOG_DEBUG(msg)
Use NS_LOG to output a message of level LOG_DEBUG.
Definition: log.h:273
#define NS_OBJECT_ENSURE_REGISTERED(type)
Register an Object subclass with the TypeId system.
Definition: object-base.h:45
Time Now(void)
create an ns3::Time instance which contains the current simulation time.
Definition: simulator.cc:287
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition: nstime.h:1244
Ptr< const TraceSourceAccessor > MakeTraceSourceAccessor(T a)
Create a TraceSourceAccessor which will control access to the underlying trace source.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
@ LOG_LEVEL_ALL
Print everything.
Definition: log.h:116
void LogComponentEnable(char const *name, enum LogLevel level)
Enable the logging output associated with that log component.
Definition: log.cc:361
Callback< R, Ts... > MakeCallback(R(T::*memPtr)(Ts...), OBJ objPtr)
Build Callbacks for class method members which take varying numbers of arguments and potentially retu...
Definition: callback.h:1648
cmd
Definition: second.py:35
bool verbose
static ns3::GlobalValue g_verbose("verbose", "Whether to enable verbose output", ns3::BooleanValue(false), ns3::MakeBooleanChecker())
void NotifyViaProbe(std::string context, double oldVal, double newVal)
void NotifyViaTraceSource(std::string context, Time oldVal, Time newVal)