core: (fixes #303) Demonstrate conditional use of ShowProgress

Assisted-by: Claude Fable 5

Author: tomhenderson

src/core/examples/sample-show-progress.cc

@@ -22,6 +22,7 @@
 #include "ns3/core-module.h"
 
 #include <chrono>
+#include <optional>
 #include <string>
 #include <thread>
 
@@ -103,18 +104,21 @@ main(int argc, char** argv)
     Time interval = Seconds(10);
     Time wait = MilliSeconds(10);
     bool verbose = false;
+    bool showProgress = true;
 
     CommandLine cmd(__FILE__);
     cmd.AddValue("stop", "Simulation duration in virtual time.", stop);
     cmd.AddValue("interval", "Approximate reporting interval, in wall clock time.", interval);
     cmd.AddValue("wait", "Wallclock time to burn on each event.", wait);
     cmd.AddValue("verbose", "Turn on verbose progress message.", verbose);
+    cmd.AddValue("showProgress", "Show progress reporting.", showProgress);
     cmd.Parse(argc, argv);
 
     std::cout << "\n"
               << cmd.GetName() << ":\n"
               << "\n"
               << "verbose progress message:  " << (verbose ? "on\n" : "off\n")
+              << "progress reporting:        " << (showProgress ? "on\n" : "off\n")
               << "target reporting interval: " << interval.As(Time::S) << "\n"
               << "average event sleep time:  " << wait.As(Time::MS) << "\n"
               << "total simulation run time: " << stop.As(Time::S) << std::endl;
@@ -123,8 +127,27 @@ main(int argc, char** argv)
     h->Event();
 
     Simulator::Stop(stop);
-    ShowProgress spinner(interval);
-    spinner.SetVerbose(verbose);
+
+    // ShowProgress begins reporting when constructed; use std::optional
+    // to construct it conditionally while keeping it alive through
+    // Simulator::Run().  Here, the "showProgress" command-line argument
+    // controls whether ShowProgress runs or not, and the "verbose"
+    // command-line argument controls the verbosity of ShowProgress's output.
+    std::optional<ShowProgress> spinner;
+    if (showProgress)
+    {
+        spinner.emplace(interval);
+        // Note that in the above statement, by default, ShowProgress
+        // writes to std::cout.  You can redirect its output to std::cerr
+        // by passing "std::cerr" as a second argument in the above.
+        spinner->SetVerbose(verbose);
+    }
+
+    // Note that if you simply want to enable ShowProgress unconditionally
+    // in your program, you can simply write, without the std::optional:
+    //
+    // ShowProgress spinner(interval);
+    // spinner.SetVerbose(verbose);
 
     Simulator::Run();
     Simulator::Destroy();

src/core/model/show-progress.h

@@ -47,13 +47,13 @@ namespace ns3
  * Example usage:
  *
  * @code
- *     int main (int arg, char ** argv)
+ *     int main(int arg, char** argv)
  *     {
- *       // Create your model
+ *         // Create your model
  *
- *       ShowProgress progress (Seconds (10), std::cerr);
- *       Simulator::Run ();
- *       Simulator::Destroy ();
+ *         ShowProgress progress(Seconds(10), std::cerr);
+ *         Simulator::Run();
+ *         Simulator::Destroy();
  *     }
  * @endcode
  *
@@ -72,6 +72,26 @@ namespace ns3
  *     Elapsed wall clock: 16s
  * @endcode
  *
+ * ShowProgress begins reporting when constructed and must remain in
+ * scope through Simulator::Run().  In particular, an instance declared
+ * inside a conditional block would be destroyed at the closing brace,
+ * before the simulation runs, and would produce no output.  To create
+ * the reporter conditionally, use std::optional:
+ *
+ * @code
+ *     bool showProgress;
+ *     CommandLine cmd(__FILE__);
+ *     cmd.AddValue("showProgress", "Show progress reporting.", showProgress);
+ *     ...
+ *     std::optional<ShowProgress> progress;
+ *     if (showProgress)
+ *     {
+ *         progress.emplace(Seconds(10), std::cerr);
+ *     }
+ *     Simulator::Run();
+ *     Simulator::Destroy();
+ * @endcode
+ *
  * A more extensive example of use is provided in sample-show-progress.cc.
  *
  * Based on a python version by Gustavo Carneiro <gjcarneiro@gmail.com>,