// 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 History;
}

#include "config.h"

#include "singleton.hh"
#include "user_interrupt_exception.hh"
#include "null_policy_exception.hh"
#include "malformed_policy_exception.hh"
#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,
      state_paused,
      state_stopped
    };

    virtual ~Simulation();

    /**
    \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 Setter for the attribute timer_interval. 

      This method is used to define how a single time unit is to be 
      interpreted when the simulation advancement mode is continue.
      The input value is in milliseconds, and it must be in range [0, 10000].
     */
    virtual void  set_timer(unsigned int) = 0;

    /**
      \see set_timer()
     */
    virtual int get_timer() const = 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 bool&) = 0;

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

    virtual state get_state() const = 0;

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

    /**
      \return The policy currently in use.
     */
    virtual CPUPolicy* get_policy() = 0;

    virtual History& get_history() = 0;

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

}


#endif