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,13 +50,43 @@ namespace sgpem
   class SG_DLLEXPORT History : public ObservedSubject 
   {
   public:
-				
+	/**
+	 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:

src/backend/policy.hh

@@ -35,22 +35,86 @@ namespace sgpem
 	class Policy;
 	
   	/**	\brief 
-		e' una Strategy che rappresenta un algoritmo di scheduling che implementa una politica
+	  It's a Strategy wich stay for a scheduling algorithm.
-  		di scheduling.
+	  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 void			configure() = 0;
+		/**
-	  virtual void 			sort_queue(Scheduler::event) const = 0;
+		  Initialize the inner components of the policy.
-	  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;
 
+		  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;
+	  
+		/**
+		  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:

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,19 +32,45 @@ 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;
+
+
+	/**
+	 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;
-    void set_duration(const int&);
+
+	/**
+	 Sets duration of this Slice.
+	 \param duration The desired duration time.
+	 */	
+	void set_duration(const int& duration);
 		
   private:
 	SchedulableList _ref;