A Discrete-Event Network Simulator
API
ns3::AsciiTraceHelper Class Reference

Manage ASCII trace files for device models. More...

#include "trace-helper.h"

Public Member Functions

 AsciiTraceHelper ()
 Create an ascii trace helper. More...
 
 ~AsciiTraceHelper ()
 Destroy an ascii trace helper. More...
 
Ptr< OutputStreamWrapperCreateFileStream (std::string filename, std::ios::openmode filemode=std::ios::out)
 Create and initialize an output stream object we'll use to write the traced bits. More...
 
std::string GetFilenameFromDevice (std::string prefix, Ptr< NetDevice > device, bool useObjectNames=true)
 Let the ascii trace helper figure out a reasonable filename to use for an ascii trace file associated with a device. More...
 
std::string GetFilenameFromInterfacePair (std::string prefix, Ptr< Object > object, uint32_t interface, bool useObjectNames=true)
 Let the ascii trace helper figure out a reasonable filename to use for an ascii trace file associated with a node. More...
 
template<typename T >
void HookDefaultDequeueSinkWithContext (Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default dequeue operation trace sink that does accept and log a trace context. More...
 
template<typename T >
void HookDefaultDequeueSinkWithoutContext (Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default dequeue operation trace sink that does not accept nor log a trace context. More...
 
template<typename T >
void HookDefaultDropSinkWithContext (Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default drop operation trace sink that does accept and log a trace context. More...
 
template<typename T >
void HookDefaultDropSinkWithoutContext (Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default drop operation trace sink that does not accept nor log a trace context. More...
 
template<typename T >
void HookDefaultEnqueueSinkWithContext (Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default enqueue operation trace sink that does accept and log a trace context. More...
 
template<typename T >
void HookDefaultEnqueueSinkWithoutContext (Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default enqueue operation trace sink that does not accept nor log a trace context. More...
 
template<typename T >
void HookDefaultReceiveSinkWithContext (Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default receive operation trace sink that does accept and log a trace context. More...
 
template<typename T >
void HookDefaultReceiveSinkWithoutContext (Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
 Hook a trace source to the default receive operation trace sink that does not accept nor log a trace context. More...
 

Static Public Member Functions

static void DefaultDequeueSinkWithContext (Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
 Basic Dequeue default trace sink. More...
 
static void DefaultDequeueSinkWithoutContext (Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
 Basic Dequeue default trace sink. More...
 
static void DefaultDropSinkWithContext (Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
 Basic Drop default trace sink. More...
 
static void DefaultDropSinkWithoutContext (Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
 Basic Drop default trace sink. More...
 
static void DefaultEnqueueSinkWithContext (Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
 Basic Enqueue default trace sink. More...
 
static void DefaultEnqueueSinkWithoutContext (Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
 Basic Enqueue default trace sink. More...
 
static void DefaultReceiveSinkWithContext (Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
 Basic Receive default trace sink. More...
 
static void DefaultReceiveSinkWithoutContext (Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
 Basic Receive default trace sink. More...
 

Detailed Description

Manage ASCII trace files for device models.

Handling ascii trace files is a common operation for ns-3 devices. It is useful to provide a common base class for dealing with these ops.

Definition at line 173 of file trace-helper.h.

Constructor & Destructor Documentation

◆ AsciiTraceHelper()

ns3::AsciiTraceHelper::AsciiTraceHelper ( )

Create an ascii trace helper.

Definition at line 182 of file trace-helper.cc.

References NS_LOG_FUNCTION_NOARGS.

◆ ~AsciiTraceHelper()

ns3::AsciiTraceHelper::~AsciiTraceHelper ( )

Destroy an ascii trace helper.

Definition at line 187 of file trace-helper.cc.

References NS_LOG_FUNCTION_NOARGS.

Member Function Documentation

◆ CreateFileStream()

Ptr< OutputStreamWrapper > ns3::AsciiTraceHelper::CreateFileStream ( std::string  filename,
std::ios::openmode  filemode = std::ios::out 
)

Create and initialize an output stream object we'll use to write the traced bits.

One of the common issues users run into when trying to use tracing in ns-3 is actually a design decision made in the C++ stream library. It is not widely known that copy and assignment of iostreams is forbidden by std::basic_ios<>. This is because it is not possible to predict the semantics of the stream desired by a user.

The tempting ns-3 idiom when tracing to a file is to create a bound callback with an ofstream as the bound object. Unfortunately, this implies a copy construction in order to get the ofstream object into the callback. This operation, as mentioned above, is forbidden by the STL. You could use a global ostream and pass a pointer to it, but that is pretty ugly. You could create an ostream on the stack and pass a pointer to it, but you may run into object lifetime issues. Ns-3 has a nice reference counted object that can solve the problem so we use one of those to carry the stream around and deal with the lifetime issues.

Parameters
filenamefile name
filemodefile mode
Returns
a smart pointer to the output stream

Definition at line 193 of file trace-helper.cc.

References NS_LOG_FUNCTION.

Referenced by DsdvManetExample::CreateDevices(), MeshTest::CreateNodes(), MobilityTraceTestCase::DoRun(), Ns3TcpLossTestCase::DoRun(), ns3::CsmaHelper::EnableAsciiInternal(), ns3::FdNetDeviceHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), ns3::PointToPointHelper::EnableAsciiInternal(), ns3::WifiPhyHelper::EnableAsciiInternal(), ns3::WimaxHelper::EnableAsciiInternal(), ns3::ClickInternetStackHelper::EnableAsciiIpv4Internal(), ns3::InternetStackHelper::EnableAsciiIpv4Internal(), ns3::InternetStackHelper::EnableAsciiIpv6Internal(), ns3::SpectrumAnalyzerHelper::Install(), RoutingExperiment::Run(), NeighborCacheExample::Run(), Experiment::Run(), TraceCwnd(), TraceDroppingState(), TraceEveryDrop(), TraceInFlight(), TraceNextRx(), TraceNextTx(), TraceQueueLength(), TraceRto(), TraceRtt(), TraceSojourn(), and TraceSsThresh().

+ Here is the caller graph for this function:

◆ DefaultDequeueSinkWithContext()

void ns3::AsciiTraceHelper::DefaultDequeueSinkWithContext ( Ptr< OutputStreamWrapper file,
std::string  context,
Ptr< const Packet p 
)
static

Basic Dequeue default trace sink.

When a packet has been sent to a device for transmission, the device is expected to place the packet onto a transmit queue even if it does not have to delay the packet at all. The device removes the packet from the transmit queue when the packet is ready to send, and this dequeue will fire a corresponding event. This event will eventually translate into a '-' operation in the trace file.

This is typically implemented by hooking the "TxQueue/Dequeue" trace hook in the device (actually the Queue in the device).

Parameters
filethe output file
contextthe context
pthe packet

Definition at line 382 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by ns3::WimaxHelper::EnableAsciiForConnection(), ns3::CsmaHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), ns3::PointToPointHelper::EnableAsciiInternal(), ns3::WimaxHelper::EnableAsciiInternal(), and HookDefaultDequeueSinkWithContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DefaultDequeueSinkWithoutContext()

void ns3::AsciiTraceHelper::DefaultDequeueSinkWithoutContext ( Ptr< OutputStreamWrapper file,
Ptr< const Packet p 
)
static

Basic Dequeue default trace sink.

When a packet has been sent to a device for transmission, the device is expected to place the packet onto a transmit queue even if it does not have to delay the packet at all. The device removes the packet from the transmit queue when the packet is ready to send, and this dequeue will fire a corresponding event. This event will eventually translate into a '-' operation in the trace file.

This is typically implemented by hooking the "TxQueue/Dequeue" trace hook in the device (actually the Queue in the device).

Parameters
filethe output file
pthe packet

Definition at line 374 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by HookDefaultDequeueSinkWithoutContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DefaultDropSinkWithContext()

void ns3::AsciiTraceHelper::DefaultDropSinkWithContext ( Ptr< OutputStreamWrapper file,
std::string  context,
Ptr< const Packet p 
)
static

Basic Drop default trace sink.

When a packet has been sent to a device for transmission, the device is expected to place the packet onto a transmit queue. If this queue is full the packet will be dropped. The device is expected to trigger an event to indicate that an outbound packet is being dropped. This event will eventually translate into a 'd' operation in the trace file.

This is typically implemented by hooking the "TxQueue/Drop" trace hook in the device (actually the Queue in the device).

Parameters
filethe output file
contextthe context
pthe packet

Definition at line 351 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by ns3::WimaxHelper::EnableAsciiForConnection(), ns3::CsmaHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), ns3::PointToPointHelper::EnableAsciiInternal(), ns3::WimaxHelper::EnableAsciiInternal(), ns3::ClickInternetStackHelper::EnableAsciiIpv4Internal(), ns3::InternetStackHelper::EnableAsciiIpv4Internal(), and HookDefaultDropSinkWithContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DefaultDropSinkWithoutContext()

void ns3::AsciiTraceHelper::DefaultDropSinkWithoutContext ( Ptr< OutputStreamWrapper file,
Ptr< const Packet p 
)
static

Basic Drop default trace sink.

When a packet has been sent to a device for transmission, the device is expected to place the packet onto a transmit queue. If this queue is full the packet will be dropped. The device is expected to trigger an event to indicate that an outbound packet is being dropped. This event will eventually translate into a 'd' operation in the trace file.

This is typically implemented by hooking the "TxQueue/Drop" trace hook in the device (actually the Queue in the device).

Parameters
filethe output file
pthe packet

Definition at line 343 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by HookDefaultDropSinkWithoutContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DefaultEnqueueSinkWithContext()

void ns3::AsciiTraceHelper::DefaultEnqueueSinkWithContext ( Ptr< OutputStreamWrapper file,
std::string  context,
Ptr< const Packet p 
)
static

Basic Enqueue default trace sink.

When a packet has been sent to a device for transmission, the device is expected to place the packet onto a transmit queue even if it does not have to delay the packet at all, if only to trigger this event. This event will eventually translate into a '+' operation in the trace file.

This is typically implemented by hooking the "TxQueue/Enqueue" trace hook in the device (actually the Queue in the device).

Parameters
filethe output file
contextthe context
pthe packet

Definition at line 321 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by ns3::WimaxHelper::EnableAsciiForConnection(), ns3::CsmaHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), ns3::PointToPointHelper::EnableAsciiInternal(), ns3::WimaxHelper::EnableAsciiInternal(), and HookDefaultEnqueueSinkWithContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DefaultEnqueueSinkWithoutContext()

void ns3::AsciiTraceHelper::DefaultEnqueueSinkWithoutContext ( Ptr< OutputStreamWrapper file,
Ptr< const Packet p 
)
static

Basic Enqueue default trace sink.

When a packet has been sent to a device for transmission, the device is expected to place the packet onto a transmit queue even if it does not have to delay the packet at all, if only to trigger this event. This event will eventually translate into a '+' operation in the trace file.

This is typically implemented by hooking the "TxQueue/Enqueue" trace hook in the device (actually the Queue in the device).

Parameters
filethe output file
pthe packet

Definition at line 313 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by HookDefaultEnqueueSinkWithoutContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DefaultReceiveSinkWithContext()

void ns3::AsciiTraceHelper::DefaultReceiveSinkWithContext ( Ptr< OutputStreamWrapper file,
std::string  context,
Ptr< const Packet p 
)
static

Basic Receive default trace sink.

When a packet is received by a device for transmission, the device is expected to trigger this event to indicate the reception has occurred. This event will eventually translate into an 'r' operation in the trace file.

This is typically implemented by hooking the "MacRx" trace hook in the device.

Parameters
filethe output file
contextthe context
pthe packet

Definition at line 410 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by ns3::CsmaHelper::EnableAsciiInternal(), ns3::FdNetDeviceHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), ns3::PointToPointHelper::EnableAsciiInternal(), and HookDefaultReceiveSinkWithContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DefaultReceiveSinkWithoutContext()

void ns3::AsciiTraceHelper::DefaultReceiveSinkWithoutContext ( Ptr< OutputStreamWrapper file,
Ptr< const Packet p 
)
static

Basic Receive default trace sink.

When a packet is received by a device for transmission, the device is expected to trigger this event to indicate the reception has occurred. This event will eventually translate into an 'r' operation in the trace file.

This is typically implemented by hooking the "MacRx" trace hook in the device.

Parameters
filethe output file
pthe packet

Definition at line 402 of file trace-helper.cc.

References ns3::Time::GetSeconds(), ns3::OutputStreamWrapper::GetStream(), ns3::Simulator::Now(), and NS_LOG_FUNCTION.

Referenced by HookDefaultReceiveSinkWithoutContext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetFilenameFromDevice()

std::string ns3::AsciiTraceHelper::GetFilenameFromDevice ( std::string  prefix,
Ptr< NetDevice device,
bool  useObjectNames = true 
)

Let the ascii trace helper figure out a reasonable filename to use for an ascii trace file associated with a device.

Parameters
prefixprefix string
deviceNetDevice
useObjectNamesuse node and device names instead of indexes
Returns
file name

Definition at line 214 of file trace-helper.cc.

References ns3::Names::FindName(), ns3::Node::GetId(), NS_ABORT_MSG_UNLESS, and NS_LOG_FUNCTION.

Referenced by ns3::CsmaHelper::EnableAsciiInternal(), ns3::FdNetDeviceHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), ns3::PointToPointHelper::EnableAsciiInternal(), ns3::WifiPhyHelper::EnableAsciiInternal(), ns3::WimaxHelper::EnableAsciiInternal(), and ns3::SpectrumAnalyzerHelper::Install().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetFilenameFromInterfacePair()

std::string ns3::AsciiTraceHelper::GetFilenameFromInterfacePair ( std::string  prefix,
Ptr< Object object,
uint32_t  interface,
bool  useObjectNames = true 
)

Let the ascii trace helper figure out a reasonable filename to use for an ascii trace file associated with a node.

Parameters
prefixprefix string
objectinterface (such as Ipv4Interface or Ipv6Interface)
interfaceinterface id
useObjectNamesuse node and device names instead of indexes
Returns
file name

Definition at line 261 of file trace-helper.cc.

References ns3::Names::FindName(), ns3::Node::GetId(), ns3::Object::GetObject(), NS_ABORT_MSG_UNLESS, and NS_LOG_FUNCTION.

Referenced by ns3::ClickInternetStackHelper::EnableAsciiIpv4Internal(), ns3::InternetStackHelper::EnableAsciiIpv4Internal(), and ns3::InternetStackHelper::EnableAsciiIpv6Internal().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ HookDefaultDequeueSinkWithContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultDequeueSinkWithContext ( Ptr< T >  object,
std::string  context,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default dequeue operation trace sink that does accept and log a trace context.

Parameters
objectobject
contextcontext string
traceNametrace source name
streamoutput stream wrapper

Definition at line 577 of file trace-helper.h.

References DefaultDequeueSinkWithContext(), ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

+ Here is the call graph for this function:

◆ HookDefaultDequeueSinkWithoutContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultDequeueSinkWithoutContext ( Ptr< T >  object,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default dequeue operation trace sink that does not accept nor log a trace context.

Parameters
objectobject
traceNametrace source name
streamoutput stream wrapper

Definition at line 563 of file trace-helper.h.

References DefaultDequeueSinkWithoutContext(), create-module::file, ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

Referenced by ns3::CsmaHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), and ns3::PointToPointHelper::EnableAsciiInternal().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ HookDefaultDropSinkWithContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultDropSinkWithContext ( Ptr< T >  object,
std::string  context,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default drop operation trace sink that does accept and log a trace context.

Parameters
objectobject
contextcontext string
traceNametrace source name
streamoutput stream wrapper

Definition at line 548 of file trace-helper.h.

References DefaultDropSinkWithContext(), ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

+ Here is the call graph for this function:

◆ HookDefaultDropSinkWithoutContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultDropSinkWithoutContext ( Ptr< T >  object,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default drop operation trace sink that does not accept nor log a trace context.

Parameters
objectobject
traceNametrace source name
streamoutput stream wrapper

Definition at line 534 of file trace-helper.h.

References DefaultDropSinkWithoutContext(), create-module::file, ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

Referenced by ns3::CsmaHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), ns3::PointToPointHelper::EnableAsciiInternal(), ns3::ClickInternetStackHelper::EnableAsciiIpv4Internal(), and ns3::InternetStackHelper::EnableAsciiIpv4Internal().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ HookDefaultEnqueueSinkWithContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultEnqueueSinkWithContext ( Ptr< T >  object,
std::string  context,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default enqueue operation trace sink that does accept and log a trace context.

Parameters
objectobject
contextcontext string
traceNametrace source name
streamoutput stream wrapper

Definition at line 519 of file trace-helper.h.

References DefaultEnqueueSinkWithContext(), ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

+ Here is the call graph for this function:

◆ HookDefaultEnqueueSinkWithoutContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultEnqueueSinkWithoutContext ( Ptr< T >  object,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default enqueue operation trace sink that does not accept nor log a trace context.

Parameters
objectobject
traceNametrace source name
streamoutput stream wrapper

Definition at line 505 of file trace-helper.h.

References DefaultEnqueueSinkWithoutContext(), create-module::file, ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

Referenced by ns3::CsmaHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), and ns3::PointToPointHelper::EnableAsciiInternal().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ HookDefaultReceiveSinkWithContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultReceiveSinkWithContext ( Ptr< T >  object,
std::string  context,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default receive operation trace sink that does accept and log a trace context.

Parameters
objectobject
contextcontext string
traceNametrace source name
streamoutput stream wrapper

Definition at line 606 of file trace-helper.h.

References DefaultReceiveSinkWithContext(), ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

+ Here is the call graph for this function:

◆ HookDefaultReceiveSinkWithoutContext()

template<typename T >
void ns3::AsciiTraceHelper::HookDefaultReceiveSinkWithoutContext ( Ptr< T >  object,
std::string  traceName,
Ptr< OutputStreamWrapper stream 
)

Hook a trace source to the default receive operation trace sink that does not accept nor log a trace context.

Parameters
objectobject
traceNametrace source name
streamoutput stream wrapper

Definition at line 592 of file trace-helper.h.

References DefaultReceiveSinkWithoutContext(), create-module::file, ns3::MakeBoundCallback(), and NS_ASSERT_MSG.

Referenced by ns3::CsmaHelper::EnableAsciiInternal(), ns3::FdNetDeviceHelper::EnableAsciiInternal(), ns3::LrWpanHelper::EnableAsciiInternal(), and ns3::PointToPointHelper::EnableAsciiInternal().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

The documentation for this class was generated from the following files: