From 914b005571fe32491c138049127260e9de4ce633 Mon Sep 17 00:00:00 2001
From: Craig Dowell <craigdo@ee.washington.edu>
Date: Thu, 8 Oct 2009 00:16:55 -0700
Subject: [PATCH] Words about tracing in tutorial

---
 doc/tutorial/building-topologies.texi | 20 ++-------
 doc/tutorial/tutorial.texi            |  1 +
 examples/tutorial/fourth.cc           | 58 +++++++++++++++++++++++++++
 examples/tutorial/wscript             |  3 ++
 4 files changed, 65 insertions(+), 17 deletions(-)
 create mode 100644 examples/tutorial/fourth.cc

diff --git a/doc/tutorial/building-topologies.texi b/doc/tutorial/building-topologies.texi
index 9208ee55a..44585005d 100644
--- a/doc/tutorial/building-topologies.texi
+++ b/doc/tutorial/building-topologies.texi
@@ -1254,8 +1254,9 @@ the discussion in @code{second.cc}.  This is the same sequence.
 Now, we spent a lot of time setting up mobility models for the wireless network
 and so it would be a shame to finish up without even showing that the STA
 nodes are actually moving around during the simulation.  Let's do this by hooking
-into the @code{MobilityModel} course change trace source.  This is usually considered
-a fairly advanced topic, but let's just go for it.
+into the @code{MobilityModel} course change trace source.  This is just a sneak
+peek into the detailed tracing section which is coming up, but this seems a very
+nice place to get an example in.
 
 As mentioned in the ``Tweaking ns-3'' section, the @command{ns-3} tracing system 
 is divided into trace sources and trace sinks, and we provide functions to 
@@ -1354,18 +1355,3 @@ they happen.
   /NodeList/7/$ns3::MobilityModel/CourseChange x = 7.18682, y = 3.29223
   /NodeList/7/$ns3::MobilityModel/CourseChange x = 7.96865, y = 2.66873
 @end verbatim
-
-If you are feeling brave, there is a list of all trace sources in the 
-@uref{http://www.nsnam.org/doxygen-release/index.html,,ns-3 Doxygen}
-which you can find in the ``Modules'' tab.
-Under the ``core'' section, you will find a link to ``The list of all trace 
-sources.''.  You may find it interesting to try and hook some of these 
-traces yourself.  Additionally in the ``Modules'' documentation, there is
-a link to ``The list of all attributes.''.  You can set the default value of 
-any of these @code{Attributes} via the command line as we have previously 
-discussed.
-
-We have just scratched the surface of @command{ns-3} in this tutorial, but we 
-hope we have hopefully covered enough to get you started doing useful work.
-
--- The @command{ns-3} development team.
diff --git a/doc/tutorial/tutorial.texi b/doc/tutorial/tutorial.texi
index f3517b3d6..80bae6a6a 100644
--- a/doc/tutorial/tutorial.texi
+++ b/doc/tutorial/tutorial.texi
@@ -91,6 +91,7 @@ see @uref{http://www.nsnam.org/docs/tutorial.pdf}.
 @include conceptual-overview.texi
 @include tweaking.texi
 @include building-topologies.texi
+@include tracing.texi
 
 @printindex cp
 
diff --git a/examples/tutorial/fourth.cc b/examples/tutorial/fourth.cc
new file mode 100644
index 000000000..800ae9e48
--- /dev/null
+++ b/examples/tutorial/fourth.cc
@@ -0,0 +1,58 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation;
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#include "ns3/object.h"
+#include "ns3/uinteger.h"
+#include "ns3/traced-value.h"
+#include "ns3/trace-source-accessor.h"
+
+#include <iostream>
+  
+using namespace ns3;
+
+class MyObject : public Object
+{
+public:
+  static TypeId GetTypeId (void)
+  {
+    static TypeId tid = TypeId ("MyObject")
+      .SetParent (Object::GetTypeId ())
+      .AddConstructor<MyObject> ()
+      .AddTraceSource ("MyInteger",
+                       "An integer value to trace.",
+                       MakeTraceSourceAccessor (&MyObject::m_myInt))
+      ;
+    return tid;
+  }
+  
+  MyObject () {}
+  TracedValue<int32_t> m_myInt;
+};
+
+void
+IntTrace (int32_t oldValue, int32_t newValue)
+{
+  std::cout << "Traced " << oldValue << " to " << newValue << std::endl;
+}
+
+int
+main (int argc, char *argv[])
+{
+  Ptr<MyObject> myObject = CreateObject<MyObject> ();
+  myObject->TraceConnectWithoutContext ("MyInteger", MakeCallback(&IntTrace));
+
+  myObject->m_myInt = 1234;
+}
diff --git a/examples/tutorial/wscript b/examples/tutorial/wscript
index 590a75c22..9966647c6 100644
--- a/examples/tutorial/wscript
+++ b/examples/tutorial/wscript
@@ -12,3 +12,6 @@ def build(bld):
         
     obj = bld.create_ns3_program('third', ['core', 'simulator', 'point-to-point', 'csma', 'wifi', 'internet-stack'])
     obj.source = 'third.cc'
+
+    obj = bld.create_ns3_program('fourth', ['core'])
+    obj.source = 'fourth.cc'