/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) 2005 INRIA

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 *

 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>

 */

#ifndef SIMULATOR_H

#define SIMULATOR_H

#include "event-id.h"

#include "event-impl.h"

#include "make-event.h"

#include "nstime.h"

#include "object-factory.h"

#include <stdint.h>

#include <string>

/**

 * @file

 * @ingroup simulator

 * ns3::Simulator declaration.

 */

namespace ns3 {

class SimulatorImpl;

class Scheduler;

/**

 * @ingroup core

 * @defgroup simulator Simulator

 * @brief Control the virtual time and the execution of simulation events. 

 */

/**

 * @ingroup simulator

 *

 * @brief Control the scheduling of simulation events. 

 *

 * The internal simulation clock is maintained

 * as a 64-bit integer in a unit specified by the user

 * 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 

 * first event inserted in the scheduling queue is scheduled to 

 * expire first.

 * 

 * 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 

{

public:

  /**

   * @param [in] 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

   * that performs no realtime synchronization.  By calling this method, you

   * can substitute in a new simulator implementation that might be multi-

   * threaded and synchronize events to a realtime clock.

   *

   * The simulator implementation can be set when the simulator is not 

   * running.

   */

  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);

  /**

   * @brief Set the scheduler type with an ObjectFactory.

   * @param [in] schedulerFactory The configured ObjectFactory.

   *

   * The event scheduler can be set at any time: the events scheduled

   * in the previous scheduler will be transfered to the new scheduler

   * before we start to use it.

   */

  static void SetScheduler (ObjectFactory schedulerFactory);

  /**

   * 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

   * to restart a new simulation with a set of calls to Simulator::Run,

   * Simulator::Schedule and Simulator::ScheduleWithContext.

   */

  static void Destroy (void);

  /**

   * 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.

   */

  static bool IsFinished (void);

  /**

   * 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.

   */

  static void Run (void);

  /**

   * 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.

   */

  static void Stop (void);

  /**

   * 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 [in] delay The stop time, relative to the current time.

   */

  static void Stop (Time const &delay);

  /**

   * @name Schedule events (in the same context) to run at a future time.

   */

  /** @{ */

  /**

   * Schedule an event to expire after @p delay.

   * This can be thought of as scheduling an event

   * for the current simulation time plus the @p delay  passed as a

   * parameter.

   *

   * When the event expires (when it becomes due to be run), the 

   * input method will be invoked on the input object.

   *

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @returns The id for the scheduled event.

   */

  template <typename MEM, typename OBJ>

  static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj);

  /**

   * @see Schedule(const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @returns The id for the scheduled event.

   */

  template <typename MEM, typename OBJ, typename T1>

  static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1);

  /**

   * @see Schedule(const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @tparam T2 @inferred Type of second argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @param [in] a2 The second argument to pass to the invoked method

   * @returns The id for the scheduled event.

   */

  template <typename MEM, typename OBJ, typename T1, typename T2>

  static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2);

  /**

   * @see Schedule(const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @tparam T2 @inferred Type of second argument.

   * @tparam T3 @inferred Type of third argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @param [in] a2 The second argument to pass to the invoked method

   * @param [in] a3 The third argument to pass to the invoked method

   * @returns The id for the scheduled event.

   */

  template <typename MEM, typename OBJ, 

            typename T1, typename T2, typename T3>

  static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3);

  /**

   * @see Schedule(const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @tparam T2 @inferred Type of second argument.

   * @tparam T3 @inferred Type of third argument.

   * @tparam T4 @inferred Type of fourth argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @param [in] a2 The second argument to pass to the invoked method

   * @param [in] a3 The third argument to pass to the invoked method

   * @param [in] a4 The fourth argument to pass to the invoked method

   * @returns The id for the scheduled event.

   */

  template <typename MEM, typename OBJ, 

            typename T1, typename T2, typename T3, typename T4>

  static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3, T4 a4);

  /**

   * @see Schedule(const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @tparam T2 @inferred Type of second argument.

   * @tparam T3 @inferred Type of third argument.

   * @tparam T4 @inferred Type of fourth argument.

   * @tparam T5 @inferred Type of fifth argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @param [in] a2 The second argument to pass to the invoked method

   * @param [in] a3 The third argument to pass to the invoked method

   * @param [in] a4 The fourth argument to pass to the invoked method

   * @param [in] a5 The fifth argument to pass to the invoked method

   * @returns The id for the scheduled event.

   */

  template <typename MEM, typename OBJ, 

            typename T1, typename T2, typename T3, typename T4, typename T5>

  static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, 

                           T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);

  /**

   * @copybrief Schedule(const Time&,MEM,OBJ)

   *

   * When the event expires (when it becomes due to be run), the

   * function will be invoked with any supplied arguments.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] f The function to invoke

   * @returns The id for the scheduled event.

   */

  static EventId Schedule (Time const &delay, void (*f)(void));

  /**

   * @see Schedule(const Time&,(*)())

   * @tparam U1 @inferred Formal type of the first argument to the function.

   * @tparam T1 @inferred Actual type of the first argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] f The function to invoke

   * @param [in] a1 The first argument to pass to the function to invoke.

   * @returns The id for the scheduled event.

   */

  template <typename U1, typename T1>

  static EventId Schedule (Time const &delay, void (*f)(U1), T1 a1);

  /**

   * @see Schedule(const Time&,(*)())

   * @tparam U1 @inferred Formal type of the first argument to the function.

   * @tparam U2 @inferred Formal type of the second argument to the function.

   * @tparam T1 @inferred Actual type of the first argument.

   * @tparam T2 @inferred Actual type of the second argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] f The function to invoke

   * @param [in] a1 The first argument to pass to the function to invoke

   * @param [in] a2 The second argument to pass to the function to invoke

   * @returns The id for the scheduled event.

   */

  template <typename U1, typename U2,

            typename T1, typename T2>

  static EventId Schedule (Time const &delay, void (*f)(U1,U2), T1 a1, T2 a2);

  /**

   * @see Schedule(const Time&,void(*)())

   * @tparam U1 @inferred Formal type of the first argument to the function.

   * @tparam U2 @inferred Formal type of the second argument to the function.

   * @tparam U3 @inferred Formal type of the third argument to the function.

   * @tparam T1 @inferred Actual type of the first argument.

   * @tparam T2 @inferred Actual type of the second argument.

   * @tparam T3 @inferred Actual type of the third argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] f The function to invoke

   * @param [in] a1 The first argument to pass to the function to invoke

   * @param [in] a2 The second argument to pass to the function to invoke

   * @param [in] a3 The third argument to pass to the function to invoke

   * @returns The id for the scheduled event.

   */

  template <typename U1, typename U2, typename U3,

            typename T1, typename T2, typename T3>

  static EventId Schedule (Time const &delay, void (*f)(U1,U2,U3), T1 a1, T2 a2, T3 a3);

  /**

   * @see Schedule(const Time&,(*)(void))

   * @tparam U1 @inferred Formal type of the first argument to the function.

   * @tparam U2 @inferred Formal type of the second argument to the function.

   * @tparam U3 @inferred Formal type of the third argument to the function.

   * @tparam U4 @inferred Formal type of the fourth argument to the function.

   * @tparam T1 @inferred Actual type of the first argument.

   * @tparam T2 @inferred Actual type of the second argument.

   * @tparam T3 @inferred Actual type of the third argument.

   * @tparam T4 @inferred Actual type of the fourth argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] f The function to invoke

   * @param [in] a1 The first argument to pass to the function to invoke

   * @param [in] a2 The second argument to pass to the function to invoke

   * @param [in] a3 The third argument to pass to the function to invoke

   * @param [in] a4 The fourth argument to pass to the function to invoke

   * @returns The id for the scheduled event.

   */

  template <typename U1, typename U2, typename U3, typename U4, 

            typename T1, typename T2, typename T3, typename T4>

  static EventId Schedule (Time const &delay, void (*f)(U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4);

  /**

   * @see Schedule(const Time&,void(*)(void))

   * @tparam U1 @inferred Formal type of the first argument to the function.

   * @tparam U2 @inferred Formal type of the second argument to the function.

   * @tparam U3 @inferred Formal type of the third argument to the function.

   * @tparam U4 @inferred Formal type of the fourth argument to the function.

   * @tparam U5 @inferred Formal type of the fifth argument to the function.

   * @tparam T1 @inferred Actual type of the first argument.

   * @tparam T2 @inferred Actual type of the second argument.

   * @tparam T3 @inferred Actual type of the third argument.

   * @tparam T4 @inferred Actual type of the fourth argument.

   * @tparam T5 @inferred Actual type of the fifth argument.

   * @param [in] delay The relative expiration time of the event.

   * @param [in] f The function to invoke

   * @param [in] a1 The first argument to pass to the function to invoke

   * @param [in] a2 The second argument to pass to the function to invoke

   * @param [in] a3 The third argument to pass to the function to invoke

   * @param [in] a4 The fourth argument to pass to the function to invoke

   * @param [in] a5 The fifth argument to pass to the function to invoke

   * @returns The id for 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 Schedule (Time const &delay, 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 now or at a future 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.

   * This method is thread-safe: it can be called from any thread.

   *

   * @see Schedule(const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @param [in] context User-specified context parameter

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   */

  template <typename MEM, typename OBJ>

  static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj);

  /**

   * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @param [in] context User-specified context parameter

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   */

  template <typename MEM, typename OBJ, typename T1>

  static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1);

  /**

   * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @tparam T2 @inferred Type of second argument.

   * @param [in] context User-specified context parameter

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @param [in] a2 The second argument to pass to the invoked method

   */

  template <typename MEM, typename OBJ, typename T1, typename T2>

  static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2);

  /**

   * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @tparam T2 @inferred Type of second argument.

   * @tparam T3 @inferred Type of third argument.

   * @param [in] context User-specified context parameter

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @param [in] a2 The second argument to pass to the invoked method

   * @param [in] a3 The third argument to pass to the invoked method

   */

  template <typename MEM, typename OBJ, 

            typename T1, typename T2, typename T3>

  static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3);

  /**

   * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)

   * @tparam MEM @inferred Class method function signature type.

   * @tparam OBJ @inferred Class type of the object.

   * @tparam T1 @inferred Type of first argument.

   * @tparam T2 @inferred Type of second argument.

   * @tparam T3 @inferred Type of third argument.

   * @tparam T4 @inferred Type of fourth argument.

   * @param [in] context User-specified context parameter

   * @param [in] delay The relative expiration time of the event.

   * @param [in] mem_ptr Member method pointer to invoke

   * @param [in] obj The object on which to invoke the member method

   * @param [in] a1 The first argument to pass to the invoked method

   * @param [in] a2 The second argument to pass to the invoked method

   * @param [in] a3 The third argument to pass to the invoked method

   * @param [in] a4 The fourth argument to pass to the invoked method

   */

  template <typename MEM, typename OBJ, 

            typename T1, typename T2, typename T3, typename T4>

  static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3, T4 a4);