// src/frontend/simulation.hh - Copyright 2005, 2006, University
//               of Padova, dept. of Pure and Applied
//               Mathematics
//
// This file is part of SGPEMv2.
//
// This is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// SGPEMv2 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 SGPEMv2; if not, write to the Free Software
// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

#ifndef SIMULATION_HH
#define SIMULATION_HH 1

namespace sgpem
{
  class ConcreteSimulation;
  class CPUPolicy;
  class ResourcePolicy;
	class SimulationObserver;
}

#include "config.h"
#include "history.hh"
#include "singleton.hh"
#include "user_interrupt_exception.hh"
#include "null_policy_exception.hh"
#include "malformed_policy_exception.hh"
#include <stdexcept>
#include <utility>
#include <vector>

namespace sgpem
{
  class Simulation;

  /**
    \brief Manages a single simulation instance.

    Starting from a base state, simulates the progress of a scheduling system.
    Given the discrete nature of the implementation, once a scheduling algorithm
    and its parameters are fixed, the state of the system is a function of time.
    This doesn't mean the behaviour of the policy is assumed to be deterministic,
    since this will restrict the range of available policies (we won't be able 
    to uselottery scheduling, for example).

    It provides methods to edit the state of the simulation, to check the 
    characteristics of the simulation (advancement speed, advancement mode) and to
    check which schedulng algorithm is currently in use.

    \remarks Implements the Observer pattern: observes classes \ref History, \ref Scheduler,
    \ref CPUPolicy.
    \remarks Implements the Controller pattern: ensures Low Coupling between the Frontend and
    the Backend layers.
   */

  class SG_DLLEXPORT Simulation : public Singleton<ConcreteSimulation>
  {
  public:
    enum state
    {
      state_running = 0xdeafd0d0,
      state_paused  = 0xbaddcafe,
      state_stopped = 0xdeadbeef
    };

    enum mode
    {
      mode_step_by_step = 0,
      mode_continuous   = 1
    };

    virtual ~Simulation() = 0;

    /**
    \brief Runs the simulation.

    Advances the simulation by one or more steps, depending on the
    actual state and on the value set with set_mode().
    */
    virtual void  run() throw(UserInterruptException, NullPolicyException, MalformedPolicyException) = 0;

    /**
      \brief Pauses a running simulation.

      It is obviously useful only when the advancement mode is continue.
      Calling again run() will cause the simulation to start from the current
      simulation step.
     */
    virtual void  pause() = 0;

    /**
      \brief Stops the simulation.

      Behaves in the same way as pause(), except that the next call to run() 
      will cause the simulation to start from the beginning.
     */
    virtual void  stop() = 0;



    /**
      \brief Jumps the simulation to the specified instant
			
			Pauses the simulation and jumps to the specified instant
     */
    virtual void  jump_to(History::position p) throw(UserInterruptException, NullPolicyException, MalformedPolicyException) = 0;


    /**
      \brief This methods allows to change the way the simulation progresses.

      If the input value is 0 (false), the simulation will advance a single time 
      step for each call to run().
      If the input value is 1 (true), the simulation will advance contiuosly, 
      waiting the time defined with set_timer() between each step, until all 
      processes have terminated, or some error happens. 
     */
    virtual void  set_mode(const mode) = 0;

    /**
      \return The simulation advancement mode: 0 if step-to-step, 1 if
      continue.
     */
    virtual mode  get_mode() const = 0;

    virtual state get_state() const = 0;

    /**
      \brief Setup the CPU policy to be used by the system.
     */
    virtual void set_policy(CPUPolicy*) = 0;

    /**
      \brief Setup the resource policy to be used by the system.
     */
    virtual void set_resource_policy(ResourcePolicy*) = 0;
    /**
      \return The CPU policy currently in use.
     */
    virtual CPUPolicy* get_policy() = 0;

    /**
      \return The resource policy currently in use.
     */
    virtual ResourcePolicy* get_resource_policy() = 0;

    virtual History& get_history() = 0;

    virtual const History& get_history() const = 0;

		virtual unsigned int get_front() const;

    /**
     * Small kludge to avoid the need for declaration of ConcreteSimulation
     * by the calling code of Simulation::get_instance()
     */
    static Simulation& get_instance();
 


    virtual void  attach(SimulationObserver& observer);
    virtual void  detach(const SimulationObserver& observer);

    /** \brief Enable/disable notifications to registered observers
     *
     * This is quite useful to disable momentarily notification while you
     * do a bunch of insertions and/or deletions in one go, in order to 
     * speed up things.
     *
     * \return The old value
     */
    virtual bool  set_notify_enabled(bool enabled = true);

  protected:
    typedef std::vector<SimulationObserver*> RegisteredObservers;
    RegisteredObservers _observers;

		// since no constructor is available, these fields must be defined in concrete subclasses.
		History::position _front;

    Simulation(); // Constructor

    virtual void notify_change();

  private:
    bool _notify;
 };

}


#endif