// src/backend/static_thread.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 STATIC_THREAD_HH
#define STATIC_THREAD_HH 1

#include "static_process.hh"
#include "static_schedulable.hh"


#include "gettext.h"

#include <glibmm/ustring.h>

#include <vector>

namespace sgpem
{
  class StaticProcess;
  class StaticRequest;

  /// \brief A StaticThread object is a StaticSchedulable object which describes a 
  /// thread and offers thread-specific information.
  /// 
  /// A StaticThread object stores the invariant characterization of a thread.
  /// It is used together with the Thread object to fulfill the needs of a 
  /// PublicSchedulable [PublicThread wannabe] user.
  /// The attributes stored in a static entity are static in the sense that 
  /// they are user-set and no inner mechanism of the Backend component may 
  /// change these attributes without the user having explicitly asked it.
  /// 
  /// This is enforced by not providing any setter method, and by making the 
  /// copy constructor private. This makes clear that if you want to edit a 
  /// static entity, you should reset the ::History, remove the old static 
  /// entity, and create a new dynamic entity for the new static one.
  ///
  /// One noteworthy thing is the actual meaning of the arrival time of a thread:
  /// it is the difference between
  /// 
  /// the instant of the simulation in which this thread requires the CPU
  /// for the first time, i.e. the instant at which its creation in the
  /// operating system is simulated, 
  /// 
  /// and
  /// 
  /// the instant of the simulation in which the process which owns
  /// this thread requires the CPU for the first time, i.e. the instant
  /// at which its creation in the operating system is simulated.
  class StaticThread;

  class SG_DLLLOCAL StaticThread : public StaticSchedulable
  {
  public:


    /// Creates a StaticThread object with definite
    /// name, father (pointer), total cpu time required, 
    /// arrival time (default is 0 [zero]) and base priority (default is 0 [zero]).
    /// 
    /// \param name the name of the thread
    /// \param process the father process
    /// \param cpu_time the total required cpu time
    /// \param arrival_time the arrival time
    /// \param base_priority the base priority
    StaticThread(const Glib::ustring& name,
                 StaticProcess& process,
                 unsigned int cpu_time,
                 unsigned int arrival_time = 0,
                 int base_priority = 0);

    /// \brief Standard virtual destructor.
    ///
    /// Standard virtual destructor.
    virtual ~StaticThread();

    /// \brief Returns the total required CPU time of the Thread.
    ///
    /// Returns the total required CPU time of the Thread.
    /// The total required CPU time is the time the Thread needs to 
    /// complete its work.
    /// 
    /// When a Thread'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.
    /// \return the total required CPU time of the Thread.
    virtual unsigned int get_total_cpu_time() const;

    /// \brief Modifies the total required CPU time of the Thread.
    ///
    /// Modifies the total required CPU time of the Thread.
    /// Returns the old total required CPU time of the Thread.
    /// The total required CPU time is the time the Thread needs to 
    /// complete its work.
    /// 
    /// When a Thread'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.
    /// \param cpu_time the new amount of total CPU time required by the thread.
    /// \return the old total required CPU time of the Thread.
    unsigned int set_total_cpu_time(unsigned int cpu_time);

    /// \brief Returns the arrival time of the Thread.
    ///
    /// Returns the arrival time of the Thread.
    /// The arrival time is the instant of the simulation when
    /// the state of the Thread is switched from future to
    /// ready.
    /// @see ::StaticThread.
    /// \return the arrival time of the Schedulable.
    virtual unsigned int get_arrival_time() const;

    /// \brief Modifies the arrival time of the Thread.
    ///
    /// Modifies the arrival time of the Thread.
    /// The arrival time is the instant of the simulation when
    /// the state of the Thread is switched from future to
    /// ready.
    /// @see ::StaticThread.
    /// \return the arrival time of the Schedulable.
    virtual unsigned int set_arrival_time(unsigned int arrival_time);

    /// \brief Returns the parent process of the Thread
    /// 
    /// This StaticThread object represents the invariant description of a thread.
    /// That thread belongs to a particular process.
    /// That process has an associated invariant description.
    /// This method returns an handle to that description.
    /// \return the parent process of the Thread
    virtual StaticProcess& get_process();

    // Caller can use directly the vector instead that
    // the "remove_request()" and "add_request()" method
    // of the design. Since this class is internal to the
    // backend anyway, this is okay.
    virtual std::vector<StaticRequest*>& get_requests();

  private:

    /// \brief Private standard copy constructor.
    StaticThread(const StaticThread&);

    /// The difference between
    /// 
    /// the instant of the simulation in which this thread requires the CPU
    /// for the first time, i.e. the instant at which its creation in the
    /// operating system is simulated, 
    /// 
    /// and
    /// 
    /// the instant of the simulation in which the process which owns
    /// this thread requires the CPU for the first time, i.e. the instant
    /// at which its creation in the operating system is simulated.
    unsigned int _start_time_delta;

    /// The total cpu time required by this thread to terminate. 
    ///
    unsigned int _required_cpu_time;
    StaticProcess* _process;
    std::vector<StaticRequest*> _static_requests;
  };

}

#endif

