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/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