[core] Document the meaning of Simulator context.

Use a symbol Simulator::NO_CONTEXT instead of hardcoded value.

src/core/examples/main-test-sync.cc

@@ -97,7 +97,7 @@ FakeNetDevice::Doit3 (void)
       //
       // Exercise the realtime relative now path
       //
-      Simulator::ScheduleWithContext(0xffffffff, Seconds(0.0), MakeEvent (&inserted_function));
+      Simulator::ScheduleWithContext(Simulator::NO_CONTEXT, Seconds(0.0), MakeEvent (&inserted_function));
       usleep (1000);
     }
 }

src/core/model/default-simulator-impl.cc

@@ -69,7 +69,7 @@ DefaultSimulatorImpl::DefaultSimulatorImpl ()
   // before ::Run is entered, the m_currentUid will be zero
   m_currentUid = 0;
   m_currentTs = 0;
-  m_currentContext = 0xffffffff;
+  m_currentContext = Simulator::NO_CONTEXT;
   m_unscheduledEvents = 0;
   m_eventsWithContextEmpty = true;
   m_main = SystemThread::Self();

src/core/model/realtime-simulator-impl.cc

@@ -88,7 +88,7 @@ RealtimeSimulatorImpl::RealtimeSimulatorImpl ()
   // before ::Run is entered, the m_currentUid will be zero
   m_currentUid = 0;
   m_currentTs = 0;
-  m_currentContext = 0xffffffff;
+  m_currentContext = Simulator::NO_CONTEXT;
   m_unscheduledEvents = 0;
 
   m_main = SystemThread::Self();

src/core/model/simulator.cc

@@ -96,7 +96,7 @@ TimePrinter (std::ostream &os)
 static void
 NodePrinter (std::ostream &os)
 {
-  if (Simulator::GetContext () == 0xffffffff)
+  if (Simulator::GetContext () == Simulator::NO_CONTEXT)
     {
       os << "-1";
     }

src/core/model/simulator.h

@@ -64,8 +64,6 @@ class Scheduler;
  * A simple example of how to use the Simulator class to schedule events
  * is shown in sample-simulator.cc:
  * @include src/core/examples/sample-simulator.cc
- *
- * @todo Define what the simulation or event context means.
  */
 class Simulator 
 {
@@ -168,6 +166,32 @@ public:
    */
   static void Stop (const Time &delay);
 
+  /**
+   * Get the current simulation context.
+   *
+   * The simulation context is the ns-3 notion of a Logical Process.
+   * Events in a single context should only modify state associated with
+   * that context. Events for objects in other contexts should be
+   * scheduled with ScheduleWithContext() to track the context switches.
+   * In other words, events in different contexts should be mutually
+   * thread safe, by not modify overlapping model state.
+   *
+   * In circumstances where the context can't be determined, such as
+   * during object initialization, the \c enum value \c NO_CONTEXT
+   * should be used.
+   *
+   * @return The current simulation context
+   */
+  static uint32_t GetContext (void);
+
+  /** Context enum values. */
+  enum {
+    /**
+     * Flag for events not associated with any particular context.
+     */
+    NO_CONTEXT = 0xffffffff
+  };
+  
   /**
    * @name Schedule events (in the same context) to run at a future time.
    */
@@ -1113,13 +1137,6 @@ public:
    */
   static Time GetMaximumSimulationTime (void);
 
-  /**
-   * Get the current simulation context.
-   *
-   * @return The current simulation context
-   */
-  static uint32_t GetContext (void);
-
   /**
    * Schedule a future event execution (in the same context).
    *

src/core/test/threaded-test-suite.cc

@@ -91,7 +91,7 @@ ThreadedSimulatorEventsTestCase::SchedulingThread (std::pair<ThreadedSimulatorEv
   while (!me->m_stop)
     {
       me->m_threadWaiting[threadno] = true;
-      Simulator::ScheduleWithContext (uint32_t (-1), 
+      Simulator::ScheduleWithContext (threadno,
                                       MicroSeconds (1),
                                       &ThreadedSimulatorEventsTestCase::DoNothing, me, threadno);
       while (!me->m_stop && me->m_threadWaiting[threadno])

src/mpi/model/distributed-simulator-impl.cc

@@ -115,7 +115,7 @@ DistributedSimulatorImpl::DistributedSimulatorImpl ()
   // before ::Run is entered, the m_currentUid will be zero
   m_currentUid = 0;
   m_currentTs = 0;
-  m_currentContext = 0xffffffff;
+  m_currentContext = Simulator::NO_CONTEXT;
   m_unscheduledEvents = 0;
   m_events = 0;
 }

src/mpi/model/null-message-simulator-impl.cc

@@ -82,7 +82,7 @@ NullMessageSimulatorImpl::NullMessageSimulatorImpl ()
   // before ::Run is entered, the m_currentUid will be zero
   m_currentUid = 0;
   m_currentTs = 0;
-  m_currentContext = 0xffffffff;
+  m_currentContext = Simulator::NO_CONTEXT;
   m_unscheduledEvents = 0;
   m_events = 0;
 

src/visualizer/model/pyviz.cc

@@ -323,7 +323,7 @@ PyViz::SimulatorRunUntil (Time time)
   NS_LOG_LOGIC ("Schedule dummy callback to be called in " << (time - Simulator::Now ()));
   m_runUntil = time;
   m_stop = false;
-  Simulator::ScheduleWithContext (0xffffffff, time - Simulator::Now (), &PyViz::CallbackStopSimulation, this);
+  Simulator::ScheduleWithContext (Simulator::NO_CONTEXT, time - Simulator::Now (), &PyViz::CallbackStopSimulation, this);
 
   Ptr<SimulatorImpl> impl = Simulator::GetImplementation ();
   Ptr<VisualSimulatorImpl> visualImpl = DynamicCast<VisualSimulatorImpl> (impl);