| author | Peter D. Barnes, Jr. <barnes26@llnl.gov> |
| Mon, 17 Nov 2014 15:49:59 -0800 | |
| changeset 11091 | 4bbd7b9a2889 |
| parent 11090 | ae11bb28818a |
| child 11092 | 6afcfe8a5447 |
--- a/src/core/model/default-simulator-impl.cc Wed Nov 12 12:08:53 2014 -0800 +++ b/src/core/model/default-simulator-impl.cc Mon Nov 17 15:49:59 2014 -0800 @@ -357,30 +357,30 @@ } bool -DefaultSimulatorImpl::IsExpired (const EventId &ev) const +DefaultSimulatorImpl::IsExpired (const EventId &id) const { - if (ev.GetUid () == 2) + if (id.GetUid () == 2) { - if (ev.PeekEventImpl () == 0 || - ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 || + id.PeekEventImpl ()->IsCancelled ()) { return true; } // destroy events. for (DestroyEvents::const_iterator i = m_destroyEvents.begin (); i != m_destroyEvents.end (); i++) { - if (*i == ev) + if (*i == id) { return false; } } return true; } - if (ev.PeekEventImpl () == 0 || - ev.GetTs () < m_currentTs || - (ev.GetTs () == m_currentTs && - ev.GetUid () <= m_currentUid) || - ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 || + id.GetTs () < m_currentTs || + (id.GetTs () == m_currentTs && + id.GetUid () <= m_currentUid) || + id.PeekEventImpl ()->IsCancelled ()) { return true; }
--- a/src/core/model/default-simulator-impl.h Wed Nov 12 12:08:53 2014 -0800 +++ b/src/core/model/default-simulator-impl.h Mon Nov 17 15:49:59 2014 -0800 @@ -35,6 +35,8 @@ /** * \ingroup simulator + * + * The default single process simulator implementation. */ class DefaultSimulatorImpl : public SimulatorImpl { @@ -52,9 +54,9 @@ virtual void ScheduleWithContext (uint32_t context, Time const &time, EventImpl *event); virtual EventId ScheduleNow (EventImpl *event); virtual EventId ScheduleDestroy (EventImpl *event); - virtual void Remove (const EventId &ev); - virtual void Cancel (const EventId &ev); - virtual bool IsExpired (const EventId &ev) const; + virtual void Remove (const EventId &id); + virtual void Cancel (const EventId &id); + virtual bool IsExpired (const EventId &id) const; virtual void Run (void); virtual Time Now (void) const; virtual Time GetDelayLeft (const EventId &id) const;
--- a/src/core/model/realtime-simulator-impl.cc Wed Nov 12 12:08:53 2014 -0800 +++ b/src/core/model/realtime-simulator-impl.cc Mon Nov 17 15:49:59 2014 -0800 @@ -750,12 +750,12 @@ } bool -RealtimeSimulatorImpl::IsExpired (const EventId &ev) const +RealtimeSimulatorImpl::IsExpired (const EventId &id) const { - if (ev.GetUid () == 2) + if (id.GetUid () == 2) { - if (ev.PeekEventImpl () == 0 || - ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 || + id.PeekEventImpl ()->IsCancelled ()) { return true; } @@ -763,7 +763,7 @@ for (DestroyEvents::const_iterator i = m_destroyEvents.begin (); i != m_destroyEvents.end (); i++) { - if (*i == ev) + if (*i == id) { return false; } @@ -779,10 +779,10 @@ // // The same is true for the next line involving the m_currentUid. // - if (ev.PeekEventImpl () == 0 || - ev.GetTs () < m_currentTs || - (ev.GetTs () == m_currentTs && ev.GetUid () <= m_currentUid) || - ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 || + id.GetTs () < m_currentTs || + (id.GetTs () == m_currentTs && id.GetUid () <= m_currentUid) || + id.PeekEventImpl ()->IsCancelled ()) { return true; }
--- a/src/core/model/realtime-simulator-impl.h Wed Nov 12 12:08:53 2014 -0800 +++ b/src/core/model/realtime-simulator-impl.h Mon Nov 17 15:49:59 2014 -0800 @@ -63,9 +63,9 @@ virtual void ScheduleWithContext (uint32_t context, Time const &time, EventImpl *event); virtual EventId ScheduleNow (EventImpl *event); virtual EventId ScheduleDestroy (EventImpl *event); - virtual void Remove (const EventId &ev); - virtual void Cancel (const EventId &ev); - virtual bool IsExpired (const EventId &ev) const; + virtual void Remove (const EventId &id); + virtual void Cancel (const EventId &id); + virtual bool IsExpired (const EventId &id) const; virtual void Run (void); virtual Time Now (void) const; virtual Time GetDelayLeft (const EventId &id) const;
--- a/src/core/model/simulator-impl.h Wed Nov 12 12:08:53 2014 -0800 +++ b/src/core/model/simulator-impl.h Mon Nov 17 15:49:59 2014 -0800 @@ -32,12 +32,26 @@ class Scheduler; +/** + * \ingroup simulator + * + * The SimulatorImpl base class. + * + * \todo Define what the simulation or event context means. + */ class SimulatorImpl : public Object { public: + + /** + * Register this type. + * \return The object TypeId. + */ static TypeId GetTypeId (void); /** + * Execute the events scheduled with ScheduleDestroy(). + * * This method is typically invoked at the end of a simulation * to avoid false-positive reports by a leak checker. * After this method has been invoked, it is actually possible @@ -46,62 +60,69 @@ */ virtual void Destroy () = 0; /** - * If there are no more events lefts to be scheduled, or if simulation - * time has already reached the "stop time" (see Simulator::Stop()), - * return true. Return false otherwise. + * Check if the simulation should finish. + * + * Reasons to finish are because there are + * no more events lefts to be scheduled, or if simulation + * time has already reached the "stop time" (see Simulator::Stop()). + * + * \return \c true if no more events or stop time reached. */ virtual bool IsFinished (void) const = 0; /** - * If an event invokes this method, it will be the last - * event scheduled by the Simulator::Run method before + * Tell the Simulator the calling event should be the last one + * executed. + * + * If a running event invokes this method, it will be the last + * event executed by the Simulator::Run method before * returning to the caller. */ virtual void Stop (void) = 0; /** + * Schedule the time delay until the Simulator should stop. + * * Force the Simulator::Run method to return to the caller when the * expiration time of the next event to be processed is greater than * or equal to the stop time. The stop time is relative to the * current simulation time. - * @param time the stop time, relative to the current time. + * \param time The stop time, relative to the current time. */ virtual void Stop (Time const &time) = 0; /** - * \param time delay until the event expires - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. + * Schedule a future event execution (in the same context). * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. + * \param time Delay until the event expires. + * \param event The event to schedule. + * \returns A unique identifier for the newly-scheduled event. */ virtual EventId Schedule (Time const &time, EventImpl *event) = 0; /** - * \param time delay until the event expires - * \param context event context - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. + * Schedule a future event execution (in a different context). * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. + * \param time Delay until the event expires. + * \param context Event context. + * \param event The event to schedule. + * \returns A unique identifier for the newly-scheduled event. */ virtual void ScheduleWithContext (uint32_t context, Time const &time, EventImpl *event) = 0; /** - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. + * Schedule an event to run at the current virtual time. * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. + * \param event The event to schedule. + * \returns A unique identifier for the newly-scheduled event. */ virtual EventId ScheduleNow (EventImpl *event) = 0; /** - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. + * Schedule an event to run at the end of the simulation, after + * the Stop() time or condition has been reached. * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. + * \param event The event to schedule. + * \returns A unique identifier for the newly-scheduled event. */ virtual EventId ScheduleDestroy (EventImpl *event) = 0; /** * Remove an event from the event list. + * * This method has the same visible effect as the * ns3::EventId::Cancel method * but its algorithmic complexity is much higher: it has often @@ -109,12 +130,13 @@ * Note that it is not possible to remove events which were scheduled * for the "destroy" time. Doing so will result in a program error (crash). * - * @param ev the event to remove from the list of scheduled events. + * \param id The event to remove from the list of scheduled events. */ - virtual void Remove (const EventId &ev) = 0; + virtual void Remove (const EventId &id) = 0; /** * Set the cancel bit on this event: the event's associated function - * will not be invoked when it expires. + * will not be invoked when it expires. + * * This method has the same visible effect as the * ns3::Simulator::Remove method but its algorithmic complexity is * much lower: it has O(1) complexity. @@ -122,10 +144,12 @@ * Note that it is not possible to cancel events which were scheduled * for the "destroy" time. Doing so will result in a program error (crash). * - * @param ev the event to cancel + * \param id the event to cancel */ - virtual void Cancel (const EventId &ev) = 0; + virtual void Cancel (const EventId &id) = 0; /** + * Check if an event has already run or been cancelled. + * * This method has O(1) complexity. * Note that it is not possible to test for the expiration of * events which were scheduled for the "destroy" time. Doing so @@ -134,39 +158,49 @@ * which means that if the code executed by the event calls * this function, it will get true. * - * @param ev the event to test for expiration - * @returns true if the event has expired, false otherwise. + * \param id The event to test for expiration. + * \returns \c true if the event has expired, false otherwise. */ - virtual bool IsExpired (const EventId &ev) const = 0; + virtual bool IsExpired (const EventId &id) const = 0; /** - * Run the simulation until one of: - * - no events are present anymore - * - the user called Simulator::Stop - * - the user called Simulator::Stop with stop time and the + * Run the simulation. + * + * The simulation will run until one of: + * - No events are present anymore + * - The user called Simulator::Stop + * - The user called Simulator::Stop with a stop time and the * expiration time of the next event to be processed * is greater than or equal to the stop time. */ virtual void Run (void) = 0; /** - * Return the "current simulation time". + * Return the current simulation virtual time. + * + * \returns The current virtual time. */ virtual Time Now (void) const = 0; /** - * \param id the event id to analyse - * \return the delay left until the input event id expires. + * Get the remaining time until this event will execute. + * + * \param id The event id to analyse. + * \return The delay left until the input event id expires. * if the event is not running, this method returns * zero. */ virtual Time GetDelayLeft (const EventId &id) const = 0; /** - * \return the maximum simulation time at which an event + * Get the maximum representable simulation time. + * + * \return The maximum simulation time at which an event * can be scheduled. * * The returned value will always be bigger than or equal to Simulator::Now. */ virtual Time GetMaximumSimulationTime (void) const = 0; /** - * \param schedulerFactory a new event scheduler factory + * Set the Scheduler to be used to manage the event list. + * + * \param schedulerFactory A new event scheduler factory. * * The event scheduler can be set at any time: the events scheduled * in the previous scheduler will be transfered to the new scheduler @@ -174,12 +208,17 @@ */ virtual void SetScheduler (ObjectFactory schedulerFactory) = 0; /** - * \return the system id for this simulator; used for - * MPI or other distributed simulations + * Get the system id of this simulator. + * + * The system id is the identifier for this simulator instance + * in a distributed simulation. For MPI this is the MPI rank. + * \return The system id for this simulator. */ virtual uint32_t GetSystemId () const = 0; /** - * \return the current simulation context + * Get the current simulation context. + * + * \return The current simulation context */ virtual uint32_t GetContext (void) const = 0; };
--- a/src/core/model/simulator.cc Wed Nov 12 12:08:53 2014 -0800 +++ b/src/core/model/simulator.cc Mon Nov 17 15:49:59 2014 -0800 @@ -44,22 +44,47 @@ // of causing recursions leading to stack overflow NS_LOG_COMPONENT_DEFINE ("Simulator"); -static GlobalValue g_simTypeImpl = GlobalValue ("SimulatorImplementationType", - "The object class to use as the simulator implementation", - StringValue ("ns3::DefaultSimulatorImpl"), - MakeStringChecker ()); +/** + * \ingroup simulator + * The specific simulator implementation to use. + * + * Must be derived from SimulatorImpl. + */ +static GlobalValue g_simTypeImpl = GlobalValue + ("SimulatorImplementationType", + "The object class to use as the simulator implementation", + StringValue ("ns3::DefaultSimulatorImpl"), + MakeStringChecker ()); +/** + * \ingroup scheduler + * The specific event scheduler implementation to use. + * + * Must be derived from Scheduler. + */ static GlobalValue g_schedTypeImpl = GlobalValue ("SchedulerType", "The object class to use as the scheduler implementation", TypeIdValue (MapScheduler::GetTypeId ()), MakeTypeIdChecker ()); +/** + * \ingroup logging + * Default TimePrinter implementation. + * + * \param [in] os The output stream to print the time on. + */ static void TimePrinter (std::ostream &os) { os << Simulator::Now ().GetSeconds () << "s"; } +/** + * \ingroup logging + * Default node id printer implementation. + * + * \param [in] os The output stream to print the node id on. + */ static void NodePrinter (std::ostream &os) { @@ -73,12 +98,23 @@ } } +/** + * \ingroup simulator + * \brief Get the static SimulatorImpl instance. + * \return The SimulatorImpl instance pointer. + */ static SimulatorImpl **PeekImpl (void) { static SimulatorImpl *impl = 0; return &impl; } +/** + * \ingroup simulator + * \brief Get the SimulatorImpl singleton. + * \return The singleton pointer. + * \see Simulator::GetImplementation() + */ static SimulatorImpl * GetImpl (void) { SimulatorImpl **pimpl = PeekImpl (); @@ -254,23 +290,23 @@ } void -Simulator::Remove (const EventId &ev) +Simulator::Remove (const EventId &id) { if (*PeekImpl () == 0) { return; } - return GetImpl ()->Remove (ev); + return GetImpl ()->Remove (id); } void -Simulator::Cancel (const EventId &ev) +Simulator::Cancel (const EventId &id) { if (*PeekImpl () == 0) { return; } - return GetImpl ()->Cancel (ev); + return GetImpl ()->Cancel (id); } bool @@ -341,6 +377,7 @@ LogSetTimePrinter (&TimePrinter); LogSetNodePrinter (&NodePrinter); } + Ptr<SimulatorImpl> Simulator::GetImplementation (void) {
--- a/src/core/model/simulator.h Wed Nov 12 12:08:53 2014 -0800 +++ b/src/core/model/simulator.h Mon Nov 17 15:49:59 2014 -0800 @@ -48,7 +48,7 @@ * * The internal simulation clock is maintained * as a 64-bit integer in a unit specified by the user - * through the TimeStepPrecision::Set function. This means that it is + * through the Time::SetResolution function. This means that it is * not possible to specify event expiration times with anything better * than this user-specified accuracy. Events whose expiration time is * the same modulo this accuracy are scheduled in FIFO order: the @@ -56,14 +56,16 @@ * expire first. * * A simple example of how to use the Simulator class to schedule events - * is shown below: + * is shown in sample-simulator.cc :: * \include src/core/examples/sample-simulator.cc + * + * \todo Define what the simulation or event context means. */ class Simulator { public: /** - * \param impl a new simulator implementation + * \param impl A new simulator implementation. * * The simulator provides a mechanism to swap out different implementations. * For example, the default implementation is a single-threaded simulator @@ -76,6 +78,23 @@ */ static void SetImplementation (Ptr<SimulatorImpl> impl); + /** + * \brief Get the SimulatorImpl singleton. + * + * \internal + * If the SimulatorImpl singleton hasn't been created yet, + * this function does so. At the same time it also creates + * the Scheduler. Both of these respect the global values + * which may have been set from the command line or through + * the Config system. + * + * As a side effect we also call LogSetTimePrinter() and + * LogSetNodePrinter() with the default implementations + * since we can't really do any logging until we have + * a SimulatorImpl and Scheduler. + + * \return The SimulatorImpl singleton. + */ static Ptr<SimulatorImpl> GetImplementation (void); /** @@ -87,51 +106,25 @@ */ static void SetScheduler (ObjectFactory schedulerFactory); - /** - * Every event scheduled by the Simulator::insertAtDestroy method is - * invoked. Then, we ensure that any memory allocated by the - * Simulator is freed. - * This method is typically invoked at the end of a simulation - * to avoid false-positive reports by a leak checker. - * After this method has been invoked, it is actually possible - * to restart a new simulation with a set of calls to Simulator::run - * and Simulator::insert_*. - */ + /** \copydoc SimulatorImpl::Destroy */ static void Destroy (void); - /** - * If there are no more events lefts to be scheduled, or if simulation - * time has already reached the "stop time" (see Simulator::Stop()), - * return true. Return false otherwise. - */ + /** \copydoc SimulatorImpl::IsFinished */ static bool IsFinished (void); + /** \copydoc SimulatorImpl::Run */ + static void Run (void); + + /** \copydoc SimulatorImpl::Stop(void) */ + static void Stop (void); + + /** \copydoc SimulatorImpl::Stop(Time const &) */ + static void Stop (Time const &time); + /** - * Run the simulation until one of: - * - no events are present anymore - * - the user called Simulator::Stop() - * - the user called Simulator::Stop(Time const &time) and the - * expiration time of the next event to be processed - * is greater than or equal to the stop time. + * \name Schedule events (in the same context) to run at a future time. */ - static void Run (void); - - /** - * If an event invokes this method, it will be the last - * event scheduled by the Simulator::run method before - * returning to the caller. - */ - static void Stop (void); - - /** - * Force the Simulator::run method to return to the caller when the - * expiration time of the next event to be processed is greater than - * or equal to the stop time. The stop time is relative to the - * current simulation time. - * @param time the stop time, relative to the current time. - */ - static void Stop (Time const &time); - + /** @{ */ /** * Schedule an event to expire at the relative time "time" * is reached. This can be thought of as scheduling an event @@ -276,6 +269,14 @@ typename T1, typename T2, typename T3, typename T4, typename T5> static EventId Schedule (Time const &time, void (*f)(U1,U2,U3,U4,U5), T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); + /** @} */ + + /** + * \name Schedule events (in a different context) to run at a particular time. + * + * See \ref main-test-sync.cc for example usage. + */ + /** @{ */ /** * Schedule an event with the given context. * A context of 0xffffffff means no context is specified. @@ -438,6 +439,12 @@ typename T1, typename T2, typename T3, typename T4, typename T5> static void ScheduleWithContext (uint32_t context, Time const &time, void (*f)(U1,U2,U3,U4,U5), T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); + /** @} */ + + /** + * \name Schedule events (in the same context) to run now. + */ + /** @{ */ /** * Schedule an event to expire Now. All events scheduled to * to expire "Now" are scheduled FIFO, after all normal events @@ -445,6 +452,7 @@ * * @param mem_ptr member method pointer to invoke * @param obj the object on which to invoke the member method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ> static EventId ScheduleNow (MEM mem_ptr, OBJ obj); @@ -453,6 +461,7 @@ * @param mem_ptr member method pointer to invoke * @param obj the object on which to invoke the member method * @param a1 the first argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1> @@ -463,6 +472,7 @@ * @param obj the object on which to invoke the member method * @param a1 the first argument to pass to the invoked method * @param a2 the second argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2> @@ -474,6 +484,7 @@ * @param a1 the first argument to pass to the invoked method * @param a2 the second argument to pass to the invoked method * @param a3 the third argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2, typename T3> @@ -486,6 +497,7 @@ * @param a2 the second argument to pass to the invoked method * @param a3 the third argument to pass to the invoked method * @param a4 the fourth argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2, typename T3, typename T4> @@ -499,6 +511,7 @@ * @param a3 the third argument to pass to the invoked method * @param a4 the fourth argument to pass to the invoked method * @param a5 the fifth argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2, typename T3, typename T4, typename T5> @@ -506,12 +519,14 @@ T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); /** * @param f the function to invoke + * @return The EventId of the scheduled event. */ static EventId ScheduleNow (void (*f)(void)); /** * @param f the function to invoke * @param a1 the first argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename T1> @@ -521,6 +536,7 @@ * @param f the function to invoke * @param a1 the first argument to pass to the function to invoke * @param a2 the second argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename T1, typename T2> @@ -531,6 +547,7 @@ * @param a1 the first argument to pass to the function to invoke * @param a2 the second argument to pass to the function to invoke * @param a3 the third argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename U3, typename T1, typename T2, typename T3> @@ -542,6 +559,7 @@ * @param a2 the second argument to pass to the function to invoke * @param a3 the third argument to pass to the function to invoke * @param a4 the fourth argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename U3, typename U4, typename T1, typename T2, typename T3, typename T4> @@ -554,11 +572,18 @@ * @param a3 the third argument to pass to the function to invoke * @param a4 the fourth argument to pass to the function to invoke * @param a5 the fifth argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename U3, typename U4, typename U5, typename T1, typename T2, typename T3, typename T4, typename T5> static EventId ScheduleNow (void (*f)(U1,U2,U3,U4,U5), T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); + /** @} */ + + /** + * \name Schedule events to run at the end of the simulation. + */ + /** @{ */ /** * Schedule an event to expire at Destroy time. All events * scheduled to expire at "Destroy" time are scheduled FIFO, @@ -567,6 +592,7 @@ * * @param mem_ptr member method pointer to invoke * @param obj the object on which to invoke the member method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ> static EventId ScheduleDestroy (MEM mem_ptr, OBJ obj); @@ -575,6 +601,7 @@ * @param mem_ptr member method pointer to invoke * @param obj the object on which to invoke the member method * @param a1 the first argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1> @@ -585,6 +612,7 @@ * @param obj the object on which to invoke the member method * @param a1 the first argument to pass to the invoked method * @param a2 the second argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2> @@ -596,6 +624,7 @@ * @param a1 the first argument to pass to the invoked method * @param a2 the second argument to pass to the invoked method * @param a3 the third argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2, typename T3> @@ -608,6 +637,7 @@ * @param a2 the second argument to pass to the invoked method * @param a3 the third argument to pass to the invoked method * @param a4 the fourth argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2, typename T3, typename T4> @@ -621,6 +651,7 @@ * @param a3 the third argument to pass to the invoked method * @param a4 the fourth argument to pass to the invoked method * @param a5 the fifth argument to pass to the invoked method + * @return The EventId of the scheduled event. */ template <typename MEM, typename OBJ, typename T1, typename T2, typename T3, typename T4, typename T5> @@ -628,12 +659,14 @@ T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); /** * @param f the function to invoke + * @return The EventId of the scheduled event. */ static EventId ScheduleDestroy (void (*f)(void)); /** * @param f the function to invoke * @param a1 the first argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename T1> @@ -643,6 +676,7 @@ * @param f the function to invoke * @param a1 the first argument to pass to the function to invoke * @param a2 the second argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename T1, typename T2> @@ -653,6 +687,7 @@ * @param a1 the first argument to pass to the function to invoke * @param a2 the second argument to pass to the function to invoke * @param a3 the third argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename U3, typename T1, typename T2, typename T3> @@ -664,6 +699,7 @@ * @param a2 the second argument to pass to the function to invoke * @param a3 the third argument to pass to the function to invoke * @param a4 the fourth argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename U3, typename U4, typename T1, typename T2, typename T3, typename T4> @@ -676,130 +712,76 @@ * @param a3 the third argument to pass to the function to invoke * @param a4 the fourth argument to pass to the function to invoke * @param a5 the fifth argument to pass to the function to invoke + * @return The EventId of the scheduled event. */ template <typename U1, typename U2, typename U3, typename U4, typename U5, typename T1, typename T2, typename T3, typename T4, typename T5> static EventId ScheduleDestroy (void (*f)(U1,U2,U3,U4,U5), T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); - /** - * Remove an event from the event list. - * This method has the same visible effect as the - * ns3::EventId::Cancel method - * but its algorithmic complexity is much higher: it has often - * O(log(n)) complexity, sometimes O(n), sometimes worse. - * Note that it is not possible to remove events which were scheduled - * for the "destroy" time. Doing so will result in a program error (crash). - * - * @param id the event to remove from the list of scheduled events. - */ + /** @} */ + + /** \copydoc SimulatorImpl::Remove */ static void Remove (const EventId &id); - /** - * Set the cancel bit on this event: the event's associated function - * will not be invoked when it expires. - * This method has the same visible effect as the - * ns3::Simulator::remove method but its algorithmic complexity is - * much lower: it has O(1) complexity. - * This method has the exact same semantics as ns3::EventId::cancel. - * Note that it is not possible to cancel events which were scheduled - * for the "destroy" time. Doing so will result in a program error (crash). - * - * @param id the event to cancel - */ + /** \copydoc SimulatorImpl::Cancel */ static void Cancel (const EventId &id); - /** - * This method has O(1) complexity. - * Note that it is not possible to test for the expiration of - * events which were scheduled for the "destroy" time. Doing so - * will result in a program error (crash). - * An event is said to "expire" when it starts being scheduled - * which means that if the code executed by the event calls - * this function, it will get true. - * - * @param id the event to test for expiration - * @returns true if the event has expired, false otherwise. - */ + /** \copydoc SimulatorImpl::IsExpired */ static bool IsExpired (const EventId &id); - /** - * Return the "current simulation time". - */ + /** \copydoc SimulatorImpl::Now */ static Time Now (void); - /** - * \param id the event id to analyse - * \returns the delay left until the input event id expires. - * if the event is not running, this method returns - * zero. - */ + /** \copydoc SimulatorImpl::GetDelayLeft */ static Time GetDelayLeft (const EventId &id); - /** - * \returns the maximum simulation time at which an event - * can be scheduled. - * - * The returned value will always be bigger than or equal to Simulator::Now. - */ + /** \copydoc SimulatorImpl::GetMaximumSimulationTime */ static Time GetMaximumSimulationTime (void); - /** - * \returns the current simulation context - */ + /** \copydoc SimulatorImpl::GetContext */ static uint32_t GetContext (void); - /** - * \param time delay until the event expires - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. - * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. - */ + /** \copydoc SimulatorImpl::Schedule */ static EventId Schedule (Time const &time, const Ptr<EventImpl> &event); - /** + /** \copydoc SimulatorImpl::ScheduleWithContext * This method is thread-safe: it can be called from any thread. - * - * \param time delay until the event expires - * \param context event context - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. - * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. */ static void ScheduleWithContext (uint32_t context, const Time &time, EventImpl *event); - /** - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. - * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. - */ + /** \copydoc SimulatorImpl::ScheduleDestroy */ static EventId ScheduleDestroy (const Ptr<EventImpl> &event); + /** \copydoc SimulatorImpl::ScheduleNow */ + static EventId ScheduleNow (const Ptr<EventImpl> &event); + + /** \copydoc SimulatorImpl::GetSystemId */ + static uint32_t GetSystemId (void); + +private: + /** Default constructor. */ + Simulator (); + /** Destructor. */ + ~Simulator (); + /** - * \param event the event to schedule - * \returns a unique identifier for the newly-scheduled event. - * - * This method will be typically used by language bindings - * to delegate events to their own subclass of the EventImpl base class. + * Implementation of the various Schedule methods. + * \param [in] time Delay until the event should execute. + * \param [in] event The event to execute. + * \return The EventId. */ - static EventId ScheduleNow (const Ptr<EventImpl> &event); - + static EventId DoSchedule (Time const &time, EventImpl *event); /** - * \returns the system id for this simulator; used for - * MPI or other distributed simulations + * Implementation of the various ScheduleNow methods. + * \param [in] event The event to execute. + * \return The EventId. */ - static uint32_t GetSystemId (void); -private: - Simulator (); - ~Simulator (); - - static EventId DoSchedule (Time const &time, EventImpl *event); static EventId DoScheduleNow (EventImpl *event); + /** + * Implementation of the various ScheduleDestroy methods. + * \param [in] event The event to execute. + * \return The EventId. + */ static EventId DoScheduleDestroy (EventImpl *event); }; @@ -811,8 +793,9 @@ * It is typically used as shown below to schedule an event * which expires at the absolute time "2 seconds": * \code - * Simulator::Schedule (Seconds (2.0) - Now (), &my_function); + * Simulator::Schedule (Seconds (2.0) - Now (), &my_function); * \endcode + * \return The current simulation time. */ Time Now (void);
--- a/src/mpi/model/distributed-simulator-impl.cc Wed Nov 12 12:08:53 2014 -0800 +++ b/src/mpi/model/distributed-simulator-impl.cc Mon Nov 17 15:49:59 2014 -0800 @@ -595,30 +595,30 @@ } bool -DistributedSimulatorImpl::IsExpired (const EventId &ev) const +DistributedSimulatorImpl::IsExpired (const EventId &id) const { - if (ev.GetUid () == 2) + if (id.GetUid () == 2) { - if (ev.PeekEventImpl () == 0 - || ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 + || id.PeekEventImpl ()->IsCancelled ()) { return true; } // destroy events. for (DestroyEvents::const_iterator i = m_destroyEvents.begin (); i != m_destroyEvents.end (); i++) { - if (*i == ev) + if (*i == id) { return false; } } return true; } - if (ev.PeekEventImpl () == 0 - || ev.GetTs () < m_currentTs - || (ev.GetTs () == m_currentTs - && ev.GetUid () <= m_currentUid) - || ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 + || id.GetTs () < m_currentTs + || (id.GetTs () == m_currentTs + && id.GetUid () <= m_currentUid) + || id.PeekEventImpl ()->IsCancelled ()) { return true; }
--- a/src/mpi/model/distributed-simulator-impl.h Wed Nov 12 12:08:53 2014 -0800 +++ b/src/mpi/model/distributed-simulator-impl.h Mon Nov 17 15:49:59 2014 -0800 @@ -115,9 +115,9 @@ virtual void ScheduleWithContext (uint32_t context, Time const &time, EventImpl *event); virtual EventId ScheduleNow (EventImpl *event); virtual EventId ScheduleDestroy (EventImpl *event); - virtual void Remove (const EventId &ev); - virtual void Cancel (const EventId &ev); - virtual bool IsExpired (const EventId &ev) const; + virtual void Remove (const EventId &id); + virtual void Cancel (const EventId &id); + virtual bool IsExpired (const EventId &id) const; virtual void Run (void); virtual Time Now (void) const; virtual Time GetDelayLeft (const EventId &id) const;
--- a/src/mpi/model/null-message-simulator-impl.cc Wed Nov 12 12:08:53 2014 -0800 +++ b/src/mpi/model/null-message-simulator-impl.cc Mon Nov 17 15:49:59 2014 -0800 @@ -527,30 +527,30 @@ } bool -NullMessageSimulatorImpl::IsExpired (const EventId &ev) const +NullMessageSimulatorImpl::IsExpired (const EventId &id) const { - if (ev.GetUid () == 2) + if (id.GetUid () == 2) { - if (ev.PeekEventImpl () == 0 - || ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 + || id.PeekEventImpl ()->IsCancelled ()) { return true; } // destroy events. for (DestroyEvents::const_iterator i = m_destroyEvents.begin (); i != m_destroyEvents.end (); i++) { - if (*i == ev) + if (*i == id) { return false; } } return true; } - if (ev.PeekEventImpl () == 0 - || ev.GetTs () < m_currentTs - || (ev.GetTs () == m_currentTs - && ev.GetUid () <= m_currentUid) - || ev.PeekEventImpl ()->IsCancelled ()) + if (id.PeekEventImpl () == 0 + || id.GetTs () < m_currentTs + || (id.GetTs () == m_currentTs + && id.GetUid () <= m_currentUid) + || id.PeekEventImpl ()->IsCancelled ()) { return true; }
--- a/src/mpi/model/null-message-simulator-impl.h Wed Nov 12 12:08:53 2014 -0800 +++ b/src/mpi/model/null-message-simulator-impl.h Mon Nov 17 15:49:59 2014 -0800 @@ -60,9 +60,9 @@ virtual void ScheduleWithContext (uint32_t context, Time const &time, EventImpl *event); virtual EventId ScheduleNow (EventImpl *event); virtual EventId ScheduleDestroy (EventImpl *event); - virtual void Remove (const EventId &ev); - virtual void Cancel (const EventId &ev); - virtual bool IsExpired (const EventId &ev) const; + virtual void Remove (const EventId &id); + virtual void Cancel (const EventId &id); + virtual bool IsExpired (const EventId &id) const; virtual void Run (void); virtual void RunOneEvent (void); virtual Time Now (void) const;
--- a/src/visualizer/model/visual-simulator-impl.cc Wed Nov 12 12:08:53 2014 -0800 +++ b/src/visualizer/model/visual-simulator-impl.cc Mon Nov 17 15:49:59 2014 -0800 @@ -197,9 +197,9 @@ } bool -VisualSimulatorImpl::IsExpired (const EventId &ev) const +VisualSimulatorImpl::IsExpired (const EventId &id) const { - return m_simulator->IsExpired (ev); + return m_simulator->IsExpired (id); } Time
--- a/src/visualizer/model/visual-simulator-impl.h Wed Nov 12 12:08:53 2014 -0800 +++ b/src/visualizer/model/visual-simulator-impl.h Mon Nov 17 15:49:59 2014 -0800 @@ -57,9 +57,9 @@ virtual void ScheduleWithContext (uint32_t context, Time const &time, EventImpl *event); virtual EventId ScheduleNow (EventImpl *event); virtual EventId ScheduleDestroy (EventImpl *event); - virtual void Remove (const EventId &ev); - virtual void Cancel (const EventId &ev); - virtual bool IsExpired (const EventId &ev) const; + virtual void Remove (const EventId &id); + virtual void Cancel (const EventId &id); + virtual bool IsExpired (const EventId &id) const; virtual void Run (void); virtual Time Now (void) const; virtual Time GetDelayLeft (const EventId &id) const;