A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
show-progress.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2017 Lawrence Livermore National Laboratory
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Gustavo Carneiro <gjc@inescporto.pt>
7 * Author: Peter D. Barnes, Jr. <pdbarnes@llnl.gov>
8 */
9
10#ifndef SHOW_PROGRESS_H
11#define SHOW_PROGRESS_H
12
13/**
14 * \file
15 * \ingroup core
16 * ns3::ShowProgress declaration.
17 */
18
19#include "event-id.h"
20#include "nstime.h"
23#include "time-printer.h"
24
25#include <iostream>
26
27namespace ns3
28{
29
30/**
31 * \ingroup core
32 * \ingroup debugging
33 *
34 * Periodically print a status message indicating simulator progress.
35 *
36 * Print a status message showing the simulator time and
37 * execution speed, relative to wall clock time, as well as the number
38 * of events executed each interval of wall clock time.
39 *
40 * The output interval is based on wall clock time, rather than simulation
41 * time, to avoid too many events for fast simulations, and too long of
42 * a reporting interval for very slow simulations.
43 *
44 * The target update interval (and output stream) can be configured
45 * at construction. The default output stream, if unspecified, is cout.
46 *
47 * Example usage:
48 *
49 * \code
50 * int main (int arg, char ** argv)
51 * {
52 * // Create your model
53 *
54 * ShowProgress progress (Seconds (10), std::cerr);
55 * Simulator::Run ();
56 * Simulator::Destroy ();
57 * }
58 * \endcode
59 *
60 * This generates output similar to the following:
61 *
62 * \code
63 * Start wall clock: Tue May 19 10:24:07 2020
64 * +17.179869183s ( 4.937x real time) 29559 events processed
65 * +25.769803775s ( 4.965x real time) 45179 events processed
66 * +51.539607551s ( 8.810x real time) 49421 events processed
67 * +90.324463739s ( 7.607x real time) 58021 events processed
68 * +129.770882188s ( 7.576x real time) 53850 events processed
69 * +170.958751090s ( 8.321x real time) 56473 events processed
70 * +194.339562435s ( 12.776x real time) 30957 events processed
71 * End wall clock: Tue May 19 10:24:23 2020
72 * Elapsed wall clock: 16s
73 * \endcode
74 *
75 * A more extensive example of use is provided in sample-show-progress.cc.
76 *
77 * Based on a python version by Gustavo Carneiro <gjcarneiro@gmail.com>,
78 * as released here:
79 *
80 * https://mailman.isi.edu/pipermail/ns-developers/2009-January/005039.html
81 */
83{
84 public:
85 /**
86 * Constructor.
87 * \param [in] interval The target wallclock interval to show progress.
88 * \param [in] os The stream to print on.
89 */
90 ShowProgress(const Time interval = Seconds(1.0), std::ostream& os = std::cout);
91
92 /** Destructor. */
94
95 /**
96 * Set the target update interval, in wallclock time.
97 * \param [in] interval The target wallclock interval to show progress.
98 */
99 void SetInterval(const Time interval);
100
101 /**
102 * Set the TimePrinter function to be used
103 * to prepend progress messages with the simulation time.
104 *
105 * The default is DefaultTimePrinter().
106 *
107 * \param [in] lp The TimePrinter function.
108 */
110
111 /**
112 * Set the output stream to show progress on.
113 * \param [in] os The output stream; defaults to std::cerr.
114 */
115 void SetStream(std::ostream& os);
116
117 /**
118 * Set verbose mode to print real and virtual time intervals.
119 *
120 * \param [in] verbose \c true to turn on verbose mode
121 */
122 void SetVerbose(bool verbose);
123
124 private:
125 /**
126 * Start the elapsed wallclock timestamp and print the start time.
127 * This is triggered by the constructor.
128 */
129 void Start();
130
131 /**
132 * Stop the elapsed wallclock timestamp and print the total elapsed time.
133 * This is triggered by the destructor.
134 */
135 void Stop();
136
137 /**
138 * Schedule the next CheckProgress.
139 */
141
142 /**
143 * Check on execution progress.
144 * This function is executed periodically, updates the internal
145 * state on rate of progress, and decides if it's time to generate
146 * output.
147 */
148 void CheckProgress();
149
150 /**
151 * Show execution progress.
152 * This function actually generates output, when directed by CheckProgress().
153 * \param [in] nEvents The actual number of events processed since the last
154 * progress output.
155 * \param [in] ratio The current ratio of elapsed wall clock time to the
156 * target update interval.
157 * \param [in] speed The execution speed relative to wall clock time.
158 */
159 void GiveFeedback(uint64_t nEvents, int64x64_t ratio, int64x64_t speed);
160
161 /**
162 * Hysteresis factor.
163 * \see Feedback()
164 */
165 static const int64x64_t HYSTERESIS;
166 /**
167 * Maximum growth factor.
168 * \see Feedback()
169 */
170 static const int64x64_t MAXGAIN;
171
172 SystemWallClockMs m_timer; //!< Wallclock timer
173 SystemWallClockTimestamp m_stamp; //!< Elapsed wallclock time.
174 Time m_elapsed; //!< Total elapsed wallclock time since last update.
175 Time m_interval; //!< The target update interval, in wallclock time
176 Time m_vtime; //!< The virtual time interval.
177 EventId m_event; //!< The next progress event.
178 uint64_t m_eventCount; //!< Simulator event count
179
180 TimePrinter m_printer; //!< The TimePrinter to use
181 std::ostream* m_os; //!< The output stream to use.
182 bool m_verbose; //!< Verbose mode flag
183 uint64_t m_repCount; //!< Number of CheckProgress events
184
185}; // class ShowProgress
186
187} // namespace ns3
188
189#endif /* SHOW_PROGRESS_H */
An identifier for simulation events.
Definition event-id.h:45
Periodically print a status message indicating simulator progress.
bool m_verbose
Verbose mode flag.
void SetVerbose(bool verbose)
Set verbose mode to print real and virtual time intervals.
std::ostream * m_os
The output stream to use.
void Start()
Start the elapsed wallclock timestamp and print the start time.
void SetTimePrinter(TimePrinter lp)
Set the TimePrinter function to be used to prepend progress messages with the simulation time.
void Stop()
Stop the elapsed wallclock timestamp and print the total elapsed time.
ShowProgress(const Time interval=Seconds(1.0), std::ostream &os=std::cout)
Constructor.
Time m_interval
The target update interval, in wallclock time.
uint64_t m_repCount
Number of CheckProgress events.
~ShowProgress()
Destructor.
void GiveFeedback(uint64_t nEvents, int64x64_t ratio, int64x64_t speed)
Show execution progress.
void SetStream(std::ostream &os)
Set the output stream to show progress on.
static const int64x64_t MAXGAIN
Maximum growth factor.
SystemWallClockTimestamp m_stamp
Elapsed wallclock time.
Time m_elapsed
Total elapsed wallclock time since last update.
Time m_vtime
The virtual time interval.
void ScheduleCheckProgress()
Schedule the next CheckProgress.
EventId m_event
The next progress event.
void CheckProgress()
Check on execution progress.
TimePrinter m_printer
The TimePrinter to use.
SystemWallClockMs m_timer
Wallclock timer.
void SetInterval(const Time interval)
Set the target update interval, in wallclock time.
static const int64x64_t HYSTERESIS
Hysteresis factor.
uint64_t m_eventCount
Simulator event count.
Measure elapsed wall clock time in milliseconds.
Utility class to record the difference between two wall-clock times.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
High precision numerical type, implementing Q64.64 fixed precision.
ns3::EventId declarations.
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition nstime.h:1308
Every class exported by the ns3 library is enclosed in the ns3 namespace.
void(* TimePrinter)(std::ostream &os)
Function signature for features requiring a time formatter, such as logging or ShowProgress.
Declaration of classes ns3::Time and ns3::TimeWithUnit, and the TimeValue implementation classes.
bool verbose
ns3::SystemWallClockMs declaration.
ns3::SystemWallClockTimestamp declaration.
Declaration of ns3::TimePrinter function pointer type and ns3::DefaultTimePrinter function.