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

@@ -50,20 +50,50 @@ namespace sgpem
   class SG_DLLEXPORT History : public ObservedSubject 
   {
   public:
-				
-    memory::smart_ptr<sgpem::SchedulableStatus>			get_scheduled_at(int time) const;
-	memory::smart_ptr<sgpem::SchedulableList>		 	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<sgpem::SchedulableStatus>	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<sgpem::SchedulableList>	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<sgpem::Slice>	_slices;
+	History(int);			//private constructor. The parameter is discarded
+	static History  _instance;
+	int             _total_time_elapsed;
+	std::vector<sgpem::Slice>	_slices;
   };
 	
 }//~ namespace sgpem

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

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

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