Periodically print a status message indicating simulator progress. More...

#include "show-progress.h"

Collaboration diagram for ns3::ShowProgress:

Public Member Functions
	ShowProgress (const Time interval=Seconds(1.0), std::ostream &os=std::cout)
	Constructor. More...

	~ShowProgress ()
	Destructor. More...

void	SetInterval (const Time interval)
	Set the target update interval, in wallclock time. More...

void	SetStream (std::ostream &os)
	Set the output stream to show progress on. More...

void	SetTimePrinter (TimePrinter lp)
	Set the TimePrinter function to be used to prepend progress messages with the simulation time. More...

void	SetVerbose (bool verbose)
	Set verbose mode to print real and virtual time intervals. More...

Private Member Functions
void	CheckProgress ()
	Check on execution progress. More...

void	GiveFeedback (uint64_t nEvents, int64x64_t ratio, int64x64_t speed)
	Show execution progress. More...

void	ScheduleCheckProgress ()
	Schedule the next CheckProgress. More...

void	Start ()
	Start the elapsed wallclock timestamp and print the start time. More...

void	Stop ()
	Stop the elapsed wallclock timestamp and print the total elapsed time. More...

Private Attributes
Time	m_elapsed
	Total elapsed wallclock time since last update. More...

EventId	m_event
	The next progress event. More...

uint64_t	m_eventCount
	Simulator event count. More...

Time	m_interval
	The target update interval, in wallclock time. More...

std::ostream *	m_os
	The output stream to use. More...

TimePrinter	m_printer
	The TimePrinter to use. More...

uint64_t	m_repCount
	Number of CheckProgress events. More...

SystemWallClockTimestamp	m_stamp
	Elapsed wallclock time. More...

SystemWallClockMs	m_timer
	Wallclock timer. More...

bool	m_verbose
	Verbose mode flag. More...

Time	m_vtime
	The virtual time interval. More...

Static Private Attributes
static const int64x64_t	HYSTERESIS = 1.414
	Hysteresis factor. More...

static const int64x64_t	MAXGAIN = 2.0
	Maximum growth factor. More...

Detailed Description

Periodically print a status message indicating simulator progress.

Print a status message showing the simulator time and execution speed, relative to wall clock time, as well as the number of events executed each interval of wall clock time.

The output interval is based on wall clock time, rather than simulation time, to avoid too many events for fast simulations, and too long of a reporting interval for very slow simulations.

The target update interval (and output stream) can be configured at construction. The default output stream, if unspecified, is cout.

Example usage:

int main (int arg, char ** argv)
{
  // Create your model
 
  ShowProgress progress (Seconds (10), std::cerr);
  Simulator::Run ();
  Simulator::Destroy ();
}

This generates output similar to the following:

Start wall clock: Tue May 19 10:24:07 2020
+17.179869183s (   4.937x real time) 29559 events processed
+25.769803775s (   4.965x real time) 45179 events processed
+51.539607551s (   8.810x real time) 49421 events processed
+90.324463739s (   7.607x real time) 58021 events processed
+129.770882188s (   7.576x real time) 53850 events processed
+170.958751090s (   8.321x real time) 56473 events processed
+194.339562435s (  12.776x real time) 30957 events processed
End wall clock:  Tue May 19 10:24:23 2020
Elapsed wall clock: 16s

A more extensive example of use is provided in sample-show-progress.cc.

Based on a python version by Gustavo Carneiro gjcar.nosp@m.neir.nosp@m.o@gma.nosp@m.il.c.nosp@m.om, as released here:

https://mailman.isi.edu/pipermail/ns-developers/2009-January/005039.html

Definition at line 93 of file show-progress.h.

Constructor & Destructor Documentation

◆ ShowProgress()

ns3::ShowProgress::ShowProgress	(	const Time	interval = `Seconds(1.0)`,
		std::ostream &	os = `std::cout`
	)

Constructor.

Parameters

[in]	interval	The target wallclock interval to show progress.
[in]	os	The stream to print on.

Definition at line 46 of file show-progress.cc.

References NS_LOG_FUNCTION, ScheduleCheckProgress(), and Start().

Here is the call graph for this function:

◆ ~ShowProgress()

ns3::ShowProgress::~ShowProgress ( )

Destructor.

Definition at line 65 of file show-progress.cc.

References Stop().

Here is the call graph for this function:

Member Function Documentation

◆ CheckProgress()

void ns3::ShowProgress::CheckProgress ( )

private

Check on execution progress.

This function is executed periodically, updates the internal state on rate of progress, and decides if it's time to generate output.

Internal: Update algorithm

We steer m_vtime to obtain updates approximately every m_interval in wall clock time. To smooth things out a little we impose a hysteresis band around m_interval where we don't change m_vtime. To avoid too rapid movements chasing spikes or dips in execution rate, we bound the change in m_vtime to a maximum factor.

In mathematical terms, we compute the ratio of elapsed wall clock time compared to the target reporting interval:

$ratio = \frac{elapsed}{target interval)}$

Graphically, the windows in ratio value and the corresponding updates to m_vtime are sketched in this figure:

                 ^
                 |
         ratio   |   vtime update
                 |
                 |
                 |   /= MAXGAIN
                 |
       MAXGAIN  -|--------------    /= min (ratio, MAXGAIN)
                 |
                 |   /= ratio
                 |
    HYSTERESIS  -|=============================================
                 |
                 |
                 |
              1 -|   No change
                 |
                 |
                 |
 1/ HYSTERESIS  -|==============================================
                 |
                 |   *= 1 / ratio
                 |
    1/ MAXGAIN  -|---------------   *=  min (1 / ratio, MAXGAIN)
                 |
                 |   *= MAXGAIN
                 |

As indicated, when ratio is outside the hysteresis band it amounts to multiplying m_vtime by the min/max of the ratio with the appropriate MAXGAIN factor.

Finally, some experimentation suggests we further dampen movement between HYSTERESIS and MAXGAIN, so we only apply half the ratio. This reduces "hunting" for a stable update period.

Todo:: Evaluate if simple exponential averaging would be more effective, simpler.

Definition at line 149 of file show-progress.cc.

References ns3::SystemWallClockMs::End(), f(), ns3::Simulator::GetEventCount(), GiveFeedback(), HYSTERESIS, m_elapsed, m_eventCount, m_interval, m_repCount, m_timer, m_vtime, MAXGAIN, ns3::MilliSeconds(), NS_LOG_FUNCTION, NS_LOG_LOGIC, and ScheduleCheckProgress().

Referenced by ScheduleCheckProgress().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GiveFeedback()

void ns3::ShowProgress::GiveFeedback	(	uint64_t	nEvents,
		int64x64_t	ratio,
		int64x64_t	speed
	)

private

Show execution progress.

This function actually generates output, when directed by CheckProgress().

Parameters

[in]	nEvents	The actual number of events processed since the last progress output.
[in]	ratio	The current ratio of elapsed wall clock time to the target update interval.
[in]	speed	The execution speed relative to wall clock time.

Definition at line 117 of file show-progress.cc.

References ns3::Time::As(), ns3::int64x64_t::GetDouble(), HYSTERESIS, m_elapsed, m_interval, m_os, m_repCount, m_verbose, m_vtime, and ns3::Time::S.

Referenced by CheckProgress().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ScheduleCheckProgress()

void ns3::ShowProgress::ScheduleCheckProgress ( )

private

Schedule the next CheckProgress.

Definition at line 108 of file show-progress.cc.

References CheckProgress(), m_event, m_timer, m_vtime, NS_LOG_FUNCTION, ns3::Simulator::Schedule(), and ns3::SystemWallClockMs::Start().

Referenced by ShowProgress(), and CheckProgress().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetInterval()

void ns3::ShowProgress::SetInterval ( const Time interval )

Set the target update interval, in wallclock time.

Parameters

[in] interval The target wallclock interval to show progress.

Definition at line 71 of file show-progress.cc.

References ns3::Simulator::Cancel(), m_event, m_interval, m_vtime, NS_LOG_FUNCTION, and Start().

Here is the call graph for this function:

◆ SetStream()

void ns3::ShowProgress::SetStream ( std::ostream & os )

Set the output stream to show progress on.

Parameters

[in] os The output stream; defaults to std::cerr.

Definition at line 102 of file show-progress.cc.

References m_os.

◆ SetTimePrinter()

void ns3::ShowProgress::SetTimePrinter ( TimePrinter lp )

Set the TimePrinter function to be used to prepend progress messages with the simulation time.

The default is DefaultTimePrinter().

Parameters

[in] lp The TimePrinter function.

Definition at line 88 of file show-progress.cc.

References m_printer, and NS_LOG_FUNCTION.

◆ SetVerbose()

void ns3::ShowProgress::SetVerbose ( bool verbose )

Set verbose mode to print real and virtual time intervals.

Parameters

[in] verbose true to turn on verbose mode

Definition at line 95 of file show-progress.cc.

References m_verbose, NS_LOG_FUNCTION, and verbose.

◆ Start()

void ns3::ShowProgress::Start ( )

private

Start the elapsed wallclock timestamp and print the start time.

This is triggered by the constructor.

Definition at line 273 of file show-progress.cc.

References m_stamp, ns3::SystemWallClockTimestamp::Stamp(), and ns3::SystemWallClockTimestamp::ToString().

Referenced by ShowProgress(), and SetInterval().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Stop()

void ns3::ShowProgress::Stop ( )

private

Stop the elapsed wallclock timestamp and print the total elapsed time.

This is triggered by the destructor.

Definition at line 280 of file show-progress.cc.

References ns3::SystemWallClockTimestamp::GetInterval(), m_stamp, ns3::SystemWallClockTimestamp::Stamp(), and ns3::SystemWallClockTimestamp::ToString().

Referenced by ~ShowProgress().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ HYSTERESIS

const int64x64_t ns3::ShowProgress::HYSTERESIS = 1.414

staticprivate

Hysteresis factor.

See also: Feedback()

Definition at line 176 of file show-progress.h.

Referenced by CheckProgress(), and GiveFeedback().

◆ m_elapsed

Time ns3::ShowProgress::m_elapsed

private

Total elapsed wallclock time since last update.

Definition at line 185 of file show-progress.h.

Referenced by CheckProgress(), and GiveFeedback().

◆ m_event

EventId ns3::ShowProgress::m_event

private

The next progress event.

Definition at line 188 of file show-progress.h.

Referenced by ScheduleCheckProgress(), and SetInterval().

◆ m_eventCount

uint64_t ns3::ShowProgress::m_eventCount

private

Simulator event count.

Definition at line 189 of file show-progress.h.

Referenced by CheckProgress().

◆ m_interval

Time ns3::ShowProgress::m_interval

private

The target update interval, in wallclock time.

Definition at line 186 of file show-progress.h.

Referenced by CheckProgress(), GiveFeedback(), and SetInterval().

◆ m_os

std::ostream* ns3::ShowProgress::m_os

private

The output stream to use.

Definition at line 192 of file show-progress.h.

Referenced by GiveFeedback(), and SetStream().

◆ m_printer

TimePrinter ns3::ShowProgress::m_printer

private

The TimePrinter to use.

Definition at line 191 of file show-progress.h.

Referenced by SetTimePrinter().

◆ m_repCount

uint64_t ns3::ShowProgress::m_repCount

private

Number of CheckProgress events.

Definition at line 194 of file show-progress.h.

Referenced by CheckProgress(), and GiveFeedback().

◆ m_stamp

SystemWallClockTimestamp ns3::ShowProgress::m_stamp

private

Elapsed wallclock time.

Definition at line 184 of file show-progress.h.

Referenced by Start(), and Stop().

◆ m_timer

SystemWallClockMs ns3::ShowProgress::m_timer

private

Wallclock timer.

Definition at line 183 of file show-progress.h.

Referenced by CheckProgress(), and ScheduleCheckProgress().

◆ m_verbose

bool ns3::ShowProgress::m_verbose

private

Verbose mode flag.

Definition at line 193 of file show-progress.h.

Referenced by GiveFeedback(), and SetVerbose().

◆ m_vtime

Time ns3::ShowProgress::m_vtime

private

The virtual time interval.

Definition at line 187 of file show-progress.h.

Referenced by CheckProgress(), GiveFeedback(), ScheduleCheckProgress(), and SetInterval().

◆ MAXGAIN

const int64x64_t ns3::ShowProgress::MAXGAIN = 2.0

staticprivate

Maximum growth factor.

See also: Feedback()

Definition at line 181 of file show-progress.h.

Referenced by CheckProgress().

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

src/core/model/show-progress.h
src/core/model/show-progress.cc

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ShowProgress()

◆ ~ShowProgress()

Member Function Documentation

◆ CheckProgress()

◆ GiveFeedback()

◆ ScheduleCheckProgress()

◆ SetInterval()

◆ SetStream()

◆ SetTimePrinter()

◆ SetVerbose()

◆ Start()

◆ Stop()

Member Data Documentation

◆ HYSTERESIS

◆ m_elapsed

◆ m_event

◆ m_eventCount

◆ m_interval

◆ m_os

◆ m_printer

◆ m_repCount

◆ m_stamp

◆ m_timer

◆ m_verbose

◆ m_vtime

◆ MAXGAIN