// src/backend/resource.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 ENVIRONMENT_HH
#define ENVIRONMENT_HH 1

#include "config.h"

#include <sgpemv2/sub_request.hh>

#include <map>
#include <utility>
#include <vector>

namespace sgpem
{
  class ReadyQueue;
  class Process;
  class Request;
  class Resource;

  /// \brief An instant of the simulation.
  /// An object of the Environment class represents a snapshot of
  /// the simulated environment taken in a fixed instant, composed
  /// by processes, threads, resources and more.
  /// A snapshot for every single entity is accessible from here.
  /// All the provided objects and data is constant.
  ///
  /// Class History provides access to Environments for each instant
  /// of the simulation.
  ///
  /// Anyway, as well as the returned collections contain non-const
  /// pointers, it will be possible to call non-const member functions
  /// on these objects. This has no consequences until someone adds
  /// non-const member functions to these classes.
  ///
  /// This class is abstract: it provides the public interface to
  /// read the content of an History.
  /// \see History

  class SG_DLLEXPORT Environment
  {
  public:
    typedef SubRequest::resource_key_t     resource_key_t;

    typedef std::vector<Process*>                 Processes;
    typedef std::map<resource_key_t, Resource*>   Resources;
    typedef std::vector<SubRequest*>              SubRequestQueue;

    /// \brief Returns an indexed set of snapshots of the processes
    /// Returns a standard vector of Process objects describing
    /// all the processes of the simulated environment at the
    /// considered instant.
    ///
    /// \return a constant set of snapshots of processes

    virtual const Processes&
    get_processes() const = 0;


    /// \brief Returns an indexed set of snapshots of the resources
    /// Returns a standard map of \code int \endcode to Resource
    /// objects describing the all resources of the simulated environment
    /// at the considered instant.
    ///
    /// The set is indexed in order to allow retreiving the requested
    /// resource of a SubRequest object.
    ///
    /// Future implementation may provide a cleaner implementation, i.e.
    /// a \code get_request \endcode function member in the SubRequest
    /// class which returns the Resource object indexed.
    ///
    /// \return an indexed constant set of snapshot of resources.

    virtual const Resources&
    get_resources() const = 0;


    /// \brief Returns a snapshot of the current request queue for a resource.
    /// Returns a standard vector of Request objects
    /// representing the queue of ready requests of threads which
    /// are waiting for getting control of a limited-access resource.
    /// \param resource the resource the requests are for
    /// \return the current ready requests queue (constant).

    virtual const SubRequestQueue&
    get_request_queue(resource_key_t resource_key) const = 0;


    /// \brief Returns a snapshot of the current scheduler's ready queue.
    /// Returns a ReadyQueue object representing the queue
    /// of ready processes or ready threads, depending on the
    /// scheduling policy, which are waiting for getting control
    /// of the CPU.
    /// \return the current ready queue (constant).

    virtual const ReadyQueue&
    get_sorted_queue() const = 0;


    /// \brief The standard virtual destructor.
    /// The standard virtual destructor.

    virtual
    ~Environment() = 0;
  };

}

#endif

