/* -*- 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"

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 microsecond units. This means that it is

 * not possible to specify event expiration times with anything better

 * than microsecond accuracy. Events whose expiration time is

 * the same 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 (SchedulerFactory const*factory);

  /**

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

   */

  template <typename T>

  static EventId Schedule (Time const &time, void (T::*mem_ptr) (void), T *obj);

  /**

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

   */

  template <typename T, typename T1>

  static EventId Schedule (Time const &time, void (T::*mem_ptr) (T1), T* obj, T1 a1);

  /**

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

   */

  template <typename T, typename T1, typename T2>

  static EventId Schedule (Time const &time, void (T::*mem_ptr) (T1,T2), T* obj, T1 a1, T2 a2);

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3>

  static EventId Schedule (Time const &time, void (T::*mem_ptr) (T1,T2,T3), T* obj, T1 a1, T2 a2, T3 a3);

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3, typename T4>

  static EventId Schedule (Time const &time, void (T::*mem_ptr) (T1,T2,T3,T4), T* obj, T1 a1, T2 a2, T3 a3, T4 a4);

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5>

  static EventId Schedule (Time const &time, void (T::*mem_ptr) (T1,T2,T3,T4,T5), T* obj, 

  						 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 T1>

  static EventId Schedule (Time const &time, void (*f) (T1), 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 T1, typename T2>

  static EventId Schedule (Time const &time, void (*f) (T1,T2), 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 T1, typename T2, typename T3>

  static EventId Schedule (Time const &time, void (*f) (T1,T2,T3), 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 T1, typename T2, typename T3, typename T4>

  static EventId Schedule (Time const &time, void (*f) (T1,T2,T3,T4), 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 T1, typename T2, typename T3, typename T4, typename T5>

  static EventId Schedule (Time const &time, void (*f) (T1,T2,T3,T4,T5), 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

   */

  template <typename T>

  static void ScheduleNow (void (T::*mem_ptr) (void), T *obj);

  /**

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

   */

  template <typename T, typename T1>

  static void ScheduleNow (void (T::*mem_ptr) (T1), T* obj, T1 a1);

  /**

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

   */

  template <typename T, typename T1, typename T2>

  static void ScheduleNow (void (T::*mem_ptr) (T1,T2), T* obj, T1 a1, T2 a2);

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3>

  static void ScheduleNow (void (T::*mem_ptr) (T1,T2,T3), T* obj, T1 a1, T2 a2, T3 a3);

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3, typename T4>

  static void ScheduleNow (void (T::*mem_ptr) (T1,T2,T3,T4), T* obj, 

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

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5>

  static void ScheduleNow (void (T::*mem_ptr) (T1,T2,T3,T4,T5), T* obj, 

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

  /**

   * @param f the function to invoke

   */

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

  /**

   * @param f the function to invoke

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

   */

  template <typename T1>

  static void ScheduleNow (void (*f) (T1), 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 T1, typename T2>

  static void ScheduleNow (void (*f) (T1,T2), 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 T1, typename T2, typename T3>

  static void ScheduleNow (void (*f) (T1,T2,T3), 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 T1, typename T2, typename T3, typename T4>

  static void ScheduleNow (void (*f) (T1,T2,T3,T4), 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 T1, typename T2, typename T3, typename T4, typename T5>

  static void ScheduleNow (void (*f) (T1,T2,T3,T4,T5), 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

   */

  template <typename T>

  static void ScheduleDestroy (void (T::*mem_ptr) (void), T *obj);

  /**

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

   */

  template <typename T, typename T1>

  static void ScheduleDestroy (void (T::*mem_ptr) (T1), T* obj, T1 a1);

  /**

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

   */

  template <typename T, typename T1, typename T2>

  static void ScheduleDestroy (void (T::*mem_ptr) (T1,T2), T* obj, T1 a1, T2 a2);

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3>

  static void ScheduleDestroy (void (T::*mem_ptr) (T1,T2,T3), T* obj, T1 a1, T2 a2, T3 a3);

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3, typename T4>

  static void ScheduleDestroy (void (T::*mem_ptr) (T1,T2,T3,T4), T* obj, 

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

  /**

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

   */

  template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5>

  static void ScheduleDestroy (void (T::*mem_ptr) (T1,T2,T3,T4,T5), T* obj, 

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

  /**

   * @param f the function to invoke

   */

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

  /**

   * @param f the function to invoke

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

   */

  template <typename T1>

  static void ScheduleDestroy (void (*f) (T1), 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 T1, typename T2>

  static void ScheduleDestroy (void (*f) (T1,T2), 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 T1, typename T2, typename T3>

  static void ScheduleDestroy (void (*f) (T1,T2,T3), 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 T1, typename T2, typename T3, typename T4>

  static void ScheduleDestroy (void (*f) (T1,T2,T3,T4), 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 T1, typename T2, typename T3, typename T4, typename T5>

  static void ScheduleDestroy (void (*f) (T1,T2,T3,T4,T5), 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 

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