From 02e69f92149aa5c030a0b8d73121392708b6c60f Mon Sep 17 00:00:00 2001 From: paolo Date: Fri, 24 Feb 2006 01:06:49 +0000 Subject: [PATCH] Documented history.hh, policy.hh, policy_manager.hh, slice.hh - ps git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@419 3ecf2c5c-341e-0410-92b4-d18e462d057c --- src/backend/history.hh | 54 +++++++++++++++----- src/backend/policy.hh | 94 +++++++++++++++++++++++++++++------ src/backend/policy_manager.hh | 15 +++++- src/backend/slice.hh | 40 ++++++++++++--- 4 files changed, 168 insertions(+), 35 deletions(-) diff --git a/src/backend/history.hh b/src/backend/history.hh index 032f19b..4e7db4d 100644 --- a/src/backend/history.hh +++ b/src/backend/history.hh @@ -50,20 +50,50 @@ namespace sgpem class SG_DLLEXPORT History : public ObservedSubject { public: - - memory::smart_ptr get_scheduled_at(int time) const; - memory::smart_ptr get_simulation_status_at(int time) const; - int get_current_time() const; - void enqueue_slice(const sgpem::SchedulableList& status); - void truncate_at(int instant); - - static History& get_instance(); + /** + Gets the \ref Schedulable object running at the specified time. + \param time The inquired time instant. + \return The Schedulable object running at the given time. + */ + memory::smart_ptr get_scheduled_at(int time) const; + + /** + Gets the status of simulation at the specified time. + \param time The inquired time instant. + \return The list of Schedulable status objects at the specified time. + */ + memory::smart_ptr get_simulation_status_at(int time) const; + + /** + Gets the current time. + \return The current history time. + */ + int get_current_time() const; + + /** + Sets the status of simulation at the current time. + \param status The list of \ref Schedulable status objects at the current time. + */ + void enqueue_slice(const sgpem::SchedulableList& status); + + /** + Remove all data in History following the specified time. + \param instant Desired cutting time. + */ + void truncate_at(int instant); + + + /** + Gets the only instance of History. + \return The Singleton instance of this object. + */ + static History& get_instance(); private: - History(int); //private constructor. The parameter is discarded - static History _instance; - int _total_time_elapsed; - std::vector _slices; + History(int); //private constructor. The parameter is discarded + static History _instance; + int _total_time_elapsed; + std::vector _slices; }; }//~ namespace sgpem diff --git a/src/backend/policy.hh b/src/backend/policy.hh index fee04ac..b0dadb9 100644 --- a/src/backend/policy.hh +++ b/src/backend/policy.hh @@ -34,28 +34,92 @@ namespace sgpem class Policy; - /** \brief - e' una Strategy che rappresenta un algoritmo di scheduling che implementa una politica - di scheduling. - */ + /** \brief + It's a Strategy wich stay for a scheduling algorithm. + It implements the related scheduling policy. + Its goal is, usually, to keep a list of Schedulable objects + mantained in a SchedulableQueue. + */ class SG_DLLEXPORT Policy { public: - virtual ~Policy(); + virtual ~Policy(); - virtual void configure() = 0; - virtual void sort_queue(Scheduler::event) const = 0; - int get_id() const; - virtual Glib::ustring get_description() const = 0; - virtual bool is_pre_emptive() const = 0; - virtual int get_time_slice() const = 0; - virtual void set_time_slice(const int&) = 0; + /** + Initialize the inner components of the policy. + + Because it's a pure virtual method, must be re-implemented + in concrete derived classes. + */ + virtual void configure() = 0; + + /** + Sort the \ref SchedulableQueue object that contain all the Schedulable objects + (Processes, Threads) still active managed by the scheduler. + + Because it's a pure virtual method, must be re-implemented + in concrete derived classes. + \param event Call reason. Needed only by some scheduling policies. + */ + virtual void sort_queue(Scheduler::event event) const = 0; + + /** + Gets the unique identifier (id) of this Policy. + \return The Policy id. + */ + int get_id() const; + + /** + Gets a string description of the policy. + + Because it's a pure virtual method, must be re-implemented + in concrete derived classes. + \return String description of the policy. + */ + virtual Glib::ustring get_description() const = 0; + + /** + Tell if this policy is preemptible. + If true, for the \ref Scheduler::SCHEDULABLE_ARRIVAL event, the + ready queue will contain also the running \ref Schedulable; + else the running Schedulable will not be in the queue. + + Because it's a pure virtual method, must be re-implemented + in concrete derived classes. + \return True if this policy is preemptible. + */ + virtual bool is_pre_emptive() const = 0; + + /** + Gets the time quantum for the policy. + + Because it's a pure virtual method, must be re-implemented + in concrete derived classes. + \return Time quantum for the policy. + */ + virtual int get_time_slice() const = 0; + + /** + Sets the time quantum for the policy. + + Because it's a pure virtual method, must be re-implemented + in concrete derived classes. + \param quantum The desired time quantum for the policy. + */ + virtual void set_time_slice(const int& quantum) = 0; - PolicyParameters& get_parameters(); + /** + Gets the parameters related with this policy. + + Because it's a pure virtual method, must be re-implemented + in concrete derived classes. + \return The policy parameters. + */ + PolicyParameters& get_parameters(); protected: - PolicyParameters _parameters; - int _id; + PolicyParameters _parameters; + int _id; }; }//~ namespace sgpem diff --git a/src/backend/policy_manager.hh b/src/backend/policy_manager.hh index bd67a13..d073245 100644 --- a/src/backend/policy_manager.hh +++ b/src/backend/policy_manager.hh @@ -25,16 +25,29 @@ #include "policy.hh" + namespace sgpem { class PolicyManager; + /** + PolicyManager is the Abstract Factory for \ref Policy objects. + */ class SG_DLLEXPORT PolicyManager { public: virtual ~PolicyManager() = 0; - + + /** + Gets THE policy (the only today) used. + Next versions will implement some other kind. + \return A reference to the policy. + */ virtual Policy& get_policy() = 0; + + /** + Init (or reset if yet initialized) the manager. + */ virtual void init() = 0; }; diff --git a/src/backend/slice.hh b/src/backend/slice.hh index a12f61e..1112aa9 100644 --- a/src/backend/slice.hh +++ b/src/backend/slice.hh @@ -32,24 +32,50 @@ namespace sgpem /** \brief Represents a slice of time during which some characteristic of the state of the simulation are constant Represents a slice of time during which some characteristic of the state of the simulation are constant. - It holds a SimulationStatus object which can be accesse through getSimulationStatus() + It holds a \ref SimulationStatus object which can be accessed through getSimulationStatus() */ class SG_DLLEXPORT Slice { public: + /** + Constructor for Slice. + \param start The Slice's starting time. + \param duration Time length of Slice. + \param status Photoshot of all \ref Schedulable during this Slice. + */ Slice(const int& start, const int& duration, const SchedulableList& status); - + + /** + Gets a constant reference to the \ref SchedulableList object for this Slice. + \return The reference (constant) to the SchedulableList object for this Slice. + */ const SchedulableList* get_simulation_status() const; - int get_started_at() const; - int get_duration() const; - void set_duration(const int&); + + + /** + Gets starting time of this Slice. + \return The starting time. + */ + int get_started_at() const; + + /** + Gets duration of this Slice. + \return The duration time. + */ + int get_duration() const; + + /** + Sets duration of this Slice. + \param duration The desired duration time. + */ + void set_duration(const int& duration); private: SchedulableList _ref; - int _started_at; - int _duration; + int _started_at; + int _duration; }; } //~ namespace sgpem