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

/*

 * Copyright (c) 2005 INRIA

 * All rights reserved.

 *

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

#include "event-id.h"

#include "event-impl.h"

#include "nstime.h"

#include "ns3/type-traits.h"

namespace ns3 {

class SimulatorPrivate;

class SchedulerFactory;

/**

 * \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 TimeStepPrecision::Set 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 below:

 * \include samples/main-simulator.cc

 */

class Simulator {

public:

  /**

   * Enable ParallelSimulation.

   * This method must be invoked before every other method exported

   * by the Simulator class.

   */

  static void EnableParallelSimulation (void);

  /**

   * Force the use of an event scheduler based on a linked-list.

   * This method must be invoked before any other method exported

   * by the Simulator class.

   *   - insert: O(n)

   *   - remove: O(1)

   */

  static void SetLinkedList (void);

  /**

   * Force the use of an event scheduler based on a binary heap.

   * This method must be invoked before any other method exported

   * by the Simulator class.

   *   - insert: O(log(n))

   *   - remove: O(log(n))

   */

  static void SetBinaryHeap (void);

  /**

   * Force the use of an event scheduler based on a std::map.

   * This method must be invoked before any other method exported

   * by the Simulator class.

   *   - insert: O(log(n))

   *   - remove: O(log(n))

   */

  static void SetStdMap (void);

  /**

   * Force the use of a user-provided event scheduler.

   * This method must be invoked before any other method exported

   * by the Simulator class.

   */

  static void SetExternal (const std::string &name);

  /**

   * Enable logging to the file identified by filename. If the file

   * does not exist, it is created. If it exists, it is destroyed and

   * re-created. Every scheduling event is logged to this file in a

   * simple text format which can be read back by the event replay

   * utility. This allows you to record the scheduling behavior of

   * a simulation, and measure the exact overhead related to

   * event scheduling with the event replay utility. It is also possible

   * to compare the performance of every scheduling algorithms on this

   * specific scheduling load.

   * This method must be invoked before any call to Simulator::run

   * @param filename the name of the file to log to 

   */

  static void EnableLogTo (char const *filename);

  /**

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

   */

  static void Destroy (void);

  /**

   * If there any any events lefts to be scheduled, return

   * true. Return false otherwise.

   */

  static bool IsFinished (void);

  /**

   * If Simulator::isFinished returns true, the behavior of this

   * method is undefined. Otherwise, it returns the microsecond-based

   * time of the next event expected to be scheduled.

   */

  static Time Next (void);

  /**

   * Run the simulation until one of:

   *   - no events are present anymore

   *   - the user called Simulator::stop

   *   - the user called Simulator::stopAtUs and the

   *     expiration time of the next event to be processed

   *     is greater than or equal to the stop 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.

   * @param time the stop time.

   */

  static void StopAt (Time const &time);

  /**

   * Schedule an event to expire when the time "now + time" 

   * is reached. When the event expires, the input method 

   * will be invoked on the input object.

   *

   * @param time the relative expiration time of the event.

   * @param mem_ptr member method pointer to invoke

   * @param obj the object on which to invoke the member method

   * @returns an id for the scheduled event.

   */

  /**

   * @param time the relative expiration time of the event.

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

   * @returns an id for the scheduled event.

   */

  /**

   * @param time the relative expiration time of the event.

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

   * @param a2 the second argument to pass to the invoked method

   * @returns an id for the scheduled event.

   */

  /**

   * @param time the relative expiration time of the event.

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

   * @param a2 the second argument to pass to the invoked method

   * @param a3 the third argument to pass to the invoked method

   * @returns an id for the scheduled event.

   */

            typename T1, typename T2, typename T3>

  /**

   * @param time the relative expiration time of the event.

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

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

   * @returns an id for the scheduled event.

   */

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

  /**

   * @param time the relative expiration time of the event.

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

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

   * @param a5 the fifth argument to pass to the invoked method

   * @returns an id for the scheduled event.

   */

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

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

  /**

   * @param time the relative expiration time of the event.

   * @param f the function to invoke

   * @returns an id for the scheduled event.

   */

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

  /**

   * @param time the relative expiration time of the event.

   * @param f the function to invoke

   * @param a1 the first argument to pass to the function to invoke

   * @returns an id for the scheduled event.

   */

  template <typename U1, typename T1>

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

  /**

   * @param time the relative expiration time of the event.

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

   * @returns an id for the scheduled event.

   */

  template <typename U1, typename U2, typename T1, typename T2>

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

  /**

   * @param time the relative expiration time of the event.

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

   * @param a3 the third argument to pass to the function to invoke

   * @returns an id for the scheduled event.

   */

  template <typename U1, typename U2, typename U3, typename T1, typename T2, typename T3>

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

  /**

   * @param time the relative expiration time of the event.

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

   * @param a3 the third argument to pass to the function to invoke

   * @param a4 the fourth argument to pass to the function to invoke

   * @returns an 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 &time, void (*f) (U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4);

  /**

   * @param time the relative expiration time of the event.

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

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

   * @returns an 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 &time, void (*f) (U1,U2,U3,U4,U5), T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);

  /**

   * Schedule an event to expire Now. All events scheduled to

   * to expire "Now" are scheduled FIFO, after all normal events

   * have expired. 

   *

   * @param mem_ptr member method pointer to invoke

   * @param obj the object on which to invoke the member method

   */

  /**

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

   */

            typename T1>

  /**

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

   * @param a2 the second argument to pass to the invoked method

   */

            typename T1, typename T2>

  /**

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

   * @param a2 the second argument to pass to the invoked method

   * @param a3 the third argument to pass to the invoked method

   */

            typename T1, typename T2, typename T3>

  /**

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

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

   */

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

  /**

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

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

   * @param a5 the fifth argument to pass to the invoked method

   */

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

  /**

   * @param f the function to invoke

   */

  static EventId ScheduleNow (void (*f) (void));

  /**

   * @param f the function to invoke

   * @param a1 the first argument to pass to the function to invoke

   */

  template <typename U1,

            typename T1>

  static EventId ScheduleNow (void (*f) (U1), T1 a1);

  /**

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

   */

  template <typename U1, typename U2,

            typename T1, typename T2>

  static EventId ScheduleNow (void (*f) (U1,U2), T1 a1, T2 a2);

  /**

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

   * @param a3 the third argument to pass to the function to invoke

   */

  template <typename U1, typename U2, typename U3,

            typename T1, typename T2, typename T3>

  static EventId ScheduleNow (void (*f) (U1,U2,U3), T1 a1, T2 a2, T3 a3);

  /**

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

   * @param a3 the third argument to pass to the function to invoke

   * @param a4 the fourth argument to pass to the function to invoke

   */

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

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

  static EventId ScheduleNow (void (*f) (U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4);

  /**

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

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

   */

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

  /**

   * Schedule an event to expire at Destroy time. All events 

   * scheduled to expire at "Destroy" time are scheduled FIFO, 

   * after all normal events have expired and only when 

   * Simulator::Destroy is invoked.

   *

   * @param mem_ptr member method pointer to invoke

   * @param obj the object on which to invoke the member method

   */

  /**

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

   */

            typename T1>

  /**

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

   * @param a2 the second argument to pass to the invoked method

   */

            typename T1, typename T2>

  /**

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

   * @param a2 the second argument to pass to the invoked method

   * @param a3 the third argument to pass to the invoked method

   */

            typename T1, typename T2, typename T3>

  /**

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

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

   */

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

  /**

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

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

   * @param a5 the fifth argument to pass to the invoked method

   */

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

  /**

   * @param f the function to invoke

   */

  static EventId ScheduleDestroy (void (*f) (void));

  /**

   * @param f the function to invoke

   * @param a1 the first argument to pass to the function to invoke

   */

  template <typename U1,

            typename T1>

  static EventId ScheduleDestroy (void (*f) (U1), T1 a1);

  /**

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

   */

  template <typename U1, typename U2,

            typename T1, typename T2>

  static EventId ScheduleDestroy (void (*f) (U1,U2), T1 a1, T2 a2);

  /**

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

   * @param a3 the third argument to pass to the function to invoke

   */

  template <typename U1, typename U2, typename U3,