// src/backend/dynamic_schedulable.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 3 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, see http://www.gnu.org/licenses/.


#ifndef DYNAMIC_SCHEDULABLE_HH
#define DYNAMIC_SCHEDULABLE_HH 1


#include <sgpemv2/schedulable.hh>
#include "static_schedulable.hh"

namespace sgpem
{

  /// \brief Desribes the state of a schedulable entity in a particular moment
  /// of the simulation.
  ///
  /// Contains part of the information used by the scheduling policies to 
  /// perform scheduling.
  /// Objects of subclasses of ::DynamicSchedulable may be created by the system
  /// via the Scheduler.step_forward() method (which then inserts them into a 
  /// ::ConcreteEnvironment), or by the user on a resetted ::History by creating
  /// one of them anew.
  /// 
  /// These objects may be destroyed only by resetting an ::History, or via one 
  /// of its methods.
  class DynamicSchedulable;

  class SG_DLLLOCAL DynamicSchedulable : public virtual Schedulable
  {
  public:
    /** \brief Object constructor */
    DynamicSchedulable();

    //DynamicSchedulable(const DynamicSchedulable& obj); //copy constructor

    /** \brief Verify if two instances represents the same situation
     *
     * This trivial overloading of the equal operator simply verifies if the
     * actual represented process is the same, and if the status is also the
     * same.
     */
    virtual bool operator==(const Schedulable&) const;

    /// \brief Returns the name of the Schedulable.
    ///
    /// Returns the name of the Schedulable.
    /// It is fetched from the associated ::StaticSchedulable object.
    /// \return the name of the Schedulable.
    virtual Glib::ustring get_name() const;

    /// \brief Returns the arrival time of the Schedulable.
    ///
    /// Returns the arrival time of the Schedulable.
    /// The arrival time is the instant of the simulation when
    /// the state of the Schedulable is switched from future to
    /// ready.
    ///
    /// The arrival time is a static (respect to the simulation) property. 
    /// It is fetched from the associated ::StaticSchedulable object.
    /// \return the arrival time of the Schedulable.
    virtual unsigned int get_arrival_time() const;

    /// \brief Returns the base priority of the Schedulable.
    ///
    /// Returns the base priority of the Schedulable.
    /// The base priority of a Schedulable is an indicator of the importance of
    /// the Schedulable. Priority-sensitive policies usually give better services
    /// to more important Schedulables.
    ///
    /// Base priority is summed to the priority push to obtain the current priority
    /// of the schedulable, which is the real parameter policies read.
    ///
    /// The base priority is a static (respect to the simulation) property.
    /// It is fetched from the associated ::StaticSchedulable object.
    /// \return the base priority of the Schedulable.
    virtual int get_base_priority() const;

    /// \brief Returns the total required CPU time of the Schedulable.
    ///
    /// Returns the total required CPU time of the Schedulable.
    /// The total required CPU time is the time the Schedulable needs to 
    /// complete its work.
    /// 
    /// When a Schedulable's elapsed CPU time equals the total required CPU time
    /// its state is set to "terminated". 
    ///
    /// The total required CPU time is a static (respect to the simulation) property.
    /// It is fetched from the associated ::StaticSchedulable object.
    /// \return the total required CPU time of the Schedulable.
    virtual unsigned int get_total_cpu_time() const;

    /// \brief Returns the current priority push of the Schedulable.
    ///
    /// Returns the current priority push of the Schedulable.
    /// The current priority push of a Schedulable is an indicator of the local 
    /// importance of the Schedulable. Priority-sensitive policies usually give
    /// better services to more important Schedulables.
    ///
    /// Base priority is summed to the priority push to obtain the current priority
    /// of the schedulable, which is the real parameter policies read.
    ///
    /// The priority push is a dynamic (respect to the simulation) property.
    /// \return the current priority push of the Schedulable.
    virtual int get_priority_push() const;

    /// \brief Sets the priority push of the Schedulable, returning the old one.
    ///
    /// Sets the current priority push of the Schedulable.
    /// The current priority push of a Schedulable is an indicator of the local 
    /// importance of the Schedulable. Priority-sensitive policies usually give
    /// better services to more important Schedulables.
    ///
    /// Base priority is summed to the priority push to obtain the current priority
    /// of the schedulable, which is the real parameter policies read.
    ///
    /// The priority push is a dynamic (respect to the simulation) property.
    /// \param new_value the new push to be set.
    /// \return the old priority push of the Schedulable.
    virtual int set_priority_push(int new_value = 0);

    /// \brief Returns the current priority of the Schedulable.
    ///
    /// Returns the current priority of the Schedulable.
    /// The current priority of a Schedulable is an indicator of the importance of
    /// the Schedulable. Priority-sensitive policies usually give better services
    /// to more important Schedulables.
    ///
    /// Base priority is summed to the priority push to obtain the current priority
    /// of the schedulable, which is the real parameter policies read.
    ///
    /// The current priority is a dynamic (respect to the simulation) property.
    /// \return the dynamic priority of the Schedulable.
    virtual int get_current_priority() const;

    /// \brief Returns the elapsed time of the Schedulable.
    ///
    /// Returns the elapsed time of the Schedulable.
    /// The elapsed time is the amount of time a Schedulable has been running.
    /// until the current instant.
    ///
    /// The elapsed time is a dynamic (respect to the simulation) property.
    /// \return the elapsed time of the Schedulable.
    virtual unsigned int get_elapsed_time() const = 0;

    /// \brief Returns a reference to the static schedulable object.
    /// 
    /// This function returns a reference to the actual schedable object.
    /// represented, along with its status, by this instance.
    virtual StaticSchedulable& get_core() = 0;

    /// \brief Returns a constant reference to the static schedulable object.
    /// 
    /// This function returns a constant reference to the actual schedable object.
    /// represented, along with its status, by this instance.
    virtual const StaticSchedulable& get_core() const = 0;

  private:
    int _priority_push;
  };
}

#endif
