update tutorial for tracing rework
authorCraig Dowell <craigdo@ee.washington.edu>
Mon, 25 Jan 2010 15:28:43 -0800
changeset 6019 adc48a1def77
parent 6018 92c388406dbe
child 6020 f8212529e82a
update tutorial for tracing rework
doc/tutorial/building-topologies.texi
doc/tutorial/tweaking.texi
--- a/doc/tutorial/building-topologies.texi	Mon Jan 25 15:06:41 2010 -0800
+++ b/doc/tutorial/building-topologies.texi	Mon Jan 25 15:28:43 2010 -0800
@@ -316,8 +316,8 @@
 you haven't encountered yet.
 
 @verbatim
-  PointToPointHelper::EnablePcapAll ("second");
-  CsmaHelper::EnablePcap ("second", csmaDevices.Get (1), true);
+  pointToPoint.EnablePcapAll ("second");
+  csma.EnablePcap ("second", csmaDevices.Get (1), true);
 @end verbatim
 
 The CSMA network is a multi-point-to-point network.  This means that there 
@@ -582,9 +582,9 @@
 @code{EnablePcap} calls with the calls below.
 
 @verbatim
-  PointToPointHelper::EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
-  CsmaHelper::EnablePcap ("second", csmaNodes.Get (nCsma)->GetId (), 0, false);
-  CsmaHelper::EnablePcap ("second", csmaNodes.Get (nCsma-1)->GetId (), 0, false);
+  pointToPoint.EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
+  csma.EnablePcap ("second", csmaNodes.Get (nCsma)->GetId (), 0, false);
+  csma.EnablePcap ("second", csmaNodes.Get (nCsma-1)->GetId (), 0, false);
 @end verbatim
 
 We know that we want to create a pcap file with the base name "second" and
@@ -1082,9 +1082,9 @@
 We create just enough tracing to cover all three networks:
 
 @verbatim
-  PointToPointHelper::EnablePcapAll ("third");
+  pointToPoint.EnablePcapAll ("third");
   phy.EnablePcap ("third", apDevices.Get (0));
-  CsmaHelper::EnablePcap ("third", csmaDevices.Get (0), true);
+  csma.EnablePcap ("third", csmaDevices.Get (0), true);
 @end verbatim
 
 These three lines of code will start pcap tracing on both of the point-to-point
--- a/doc/tutorial/tweaking.texi	Mon Jan 25 15:06:41 2010 -0800
+++ b/doc/tutorial/tweaking.texi	Mon Jan 25 15:28:43 2010 -0800
@@ -812,32 +812,30 @@
 
 @cindex tracing packets
 Let's just jump right in and add some ASCII tracing output to our 
-@code{scratch/myfirst.cc} script.  
-
-The first thing you need to do is to add the following include to the top of
-the script just after the GNU GPL comment:
-
-@verbatim
-  #include <fstream>
-@end verbatim
-
-Then, right before the call to @code{Simulator::Run ()}, add the
-following lines of code:
+@code{scratch/myfirst.cc} script.  Right before the call to 
+@code{Simulator::Run ()}, add the following line of code:
 
 @verbatim
-  std::ofstream ascii;
-  ascii.open ("myfirst.tr");
-  PointToPointHelper::EnableAsciiAll (ascii);
+  pointToPoint.EnableAsciiAll (ascii.CreateFileStream ("myfirst.tr"));
 @end verbatim
 
-The first two lines are just vanilla C++ code to open a stream that will be
-written to a file named ``myfirst.tr''.  See your favorite C++ tutorial if you
-are unfamiliar with this code.  The last line of code in the snippet above
-tells @command{ns-3} that you want to enable ASCII tracing on all 
-point-to-point devices in your simulation; and you want the (provided) trace
-sinks to write out information about packet movement in ASCII format to the 
-stream provided. For those familiar with @command{ns-2}, the traced events are
-equivalent to the popular trace points that log "+", "-", "d", and "r" events.
+This line of code contains two nested method calls.  The inside method,
+@code{CreateFileStream()} uses an unnamed object idiom to create a file stream
+object on the stack (without an object  name) and pass it down to the called 
+method.  We'll go into this more in the future, but all you have to know at 
+this point is that you are creating an object representing a file named 
+``myfirst.tr'' and passing it into @code{ns-3}.  You are telling @code{ns-3} 
+to deal with the lifetime issues of the created object and also to deal with 
+problems caused by a little-known (intentional) limitation of C++ ofstream
+objects relating to copy constructors.
+
+The outside call, to @code{EnableAsciiAll()}, tells the helper that you 
+want to enable ASCII tracing on all point-to-point devices in your simulation; 
+and you want the (provided) trace sinks to write out information about packet 
+movement in ASCII format.
+
+For those familiar with @command{ns-2}, the traced events are equivalent to 
+the popular trace points that log "+", "-", "d", and "r" events.
 
 You can now build the script and run it from the command line:
 
@@ -984,7 +982,7 @@
 The code used to enable pcap tracing is a one-liner.  
 
 @verbatim
-  PointToPointHelper::EnablePcapAll ("myfirst");
+  pointToPoint.EnablePcapAll ("myfirst");
 @end verbatim
 
 Go ahead and insert this line of code after the ASCII tracing code we just 
@@ -993,7 +991,7 @@
 parameter is a prefix, not a complete file name.  The helper will actually 
 create a trace file for every point-to-point device in the simulation.  The 
 file names will be built using the prefix, the node number, the device number
- and a ``.pcap'' suffix.
+and a ``.pcap'' suffix.
 
 In our example script, we will eventually see files named ``myfirst-0-0.pcap'' 
 and ``myfirst-1-0.pcap'' which are the pcap traces for node 0-device 0 and