A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::ShowProgress Class Reference

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.
 
 ~ShowProgress ()
 Destructor.
 
void SetInterval (const Time interval)
 Set the target update interval, in wallclock time.
 
void SetStream (std::ostream &os)
 Set the output stream to show progress on.
 
void SetTimePrinter (TimePrinter lp)
 Set the TimePrinter function to be used to prepend progress messages with the simulation time.
 
void SetVerbose (bool verbose)
 Set verbose mode to print real and virtual time intervals.
 

Private Member Functions

void CheckProgress ()
 Check on execution progress.
 
void GiveFeedback (uint64_t nEvents, int64x64_t ratio, int64x64_t speed)
 Show execution progress.
 
void ScheduleCheckProgress ()
 Schedule the next CheckProgress.
 
void Start ()
 Start the elapsed wallclock timestamp and print the start time.
 
void Stop ()
 Stop the elapsed wallclock timestamp and print the total elapsed time.
 

Private Attributes

Time m_elapsed
 Total elapsed wallclock time since last update.
 
EventId m_event
 The next progress event.
 
uint64_t m_eventCount
 Simulator event count.
 
Time m_interval
 The target update interval, in wallclock time.
 
std::ostream * m_os
 The output stream to use.
 
TimePrinter m_printer
 The TimePrinter to use.
 
uint64_t m_repCount
 Number of CheckProgress events.
 
SystemWallClockTimestamp m_stamp
 Elapsed wallclock time.
 
SystemWallClockMs m_timer
 Wallclock timer.
 
bool m_verbose
 Verbose mode flag.
 
Time m_vtime
 The virtual time interval.
 

Static Private Attributes

static const int64x64_t HYSTERESIS = 1.414
 Hysteresis factor.
 
static const int64x64_t MAXGAIN = 2.0
 Maximum growth factor.
 

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);
}
Periodically print a status message indicating simulator progress.
Definition: show-progress.h:94
static void Destroy()
Execute the events scheduled with ScheduleDestroy().
Definition: simulator.cc:140
static void Run()
Run the simulation.
Definition: simulator.cc:176
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition: nstime.h:1336

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
void Start()
Start the elapsed wallclock timestamp and print the start time.

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]intervalThe target wallclock interval to show progress.
[in]osThe 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]nEventsThe actual number of events processed since the last progress output.
[in]ratioThe current ratio of elapsed wall clock time to the target update interval.
[in]speedThe 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]intervalThe 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]osThe 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]lpThe 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]verbosetrue 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: