- "Commenting The Source(tm)" 02-2006 - The best summer camp of the world - First part

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@405 3ecf2c5c-341e-0410-92b4-d18e462d057c

src/backend/schedulable_status.cc

@@ -19,14 +19,22 @@
 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 
 #include "schedulable_status.hh"
+
 using namespace sgpem;
 using namespace std;
 
-SchedulableStatus::SchedulableStatus(const Schedulable& obj)
-  : _ref(&obj), _last(-1), _time_left(obj.get_total_cpu_time()), _my_state(state_future)
+SchedulableStatus::SchedulableStatus(const Schedulable& obj) :
+  _ref(&obj), _last(-1), _time_left(obj.get_total_cpu_time()),
+  _my_state(state_future)
 {
 }
 
+bool
+SchedulableStatus::operator==(const SchedulableStatus& dx) const
+{
+  return (_ref==dx._ref)&&(_last==dx._last)&&(_time_left==dx._time_left)&&(_my_state==dx._my_state);
+}
+
 int
 SchedulableStatus::get_cpu_time_left() const
 {
@@ -70,12 +78,3 @@ SchedulableStatus::get_schedulable() const
 {
   return _ref;
 }
-
-bool
-SchedulableStatus::operator==(const SchedulableStatus& dx) const 
-{
-  return (_ref==dx._ref)&&(_last==dx._last)&&(_time_left==dx._time_left)&&(_my_state==dx._my_state);
-}
-
-				 
-

src/backend/schedulable_status.hh

@@ -26,51 +26,82 @@
 
 namespace sgpem
 {
-
   class SchedulableStatus;
-  /** \brief Desribes the state of a schedulable entity in a particular moment of the simulation
 
-      This class desribes the state of a schedulable entity in a particular moment of the simulation.	
-      Stores part of informations deeded by Scheduler to manage processes and other ones.
-	
-      Objects SchedulableStatus are created by Scheduler and destroyed by  SimulationStatus if they are linked to it 
-      or by Scheduler.
-  */
+  /** \brief Desribes the state of a schedulable entity in a particular moment
+   * of the simulation
+   *
+   * This class stores part of the information deeded by the Scheduler to
+   * manage processes and other ones.
+   *
+   * Objects of type SchedulableStatus are created by the Scheduler and are
+   * destroyed by SimulationStatus if they are linked to it or by the Scheduler.
+   */
   class SG_DLLEXPORT SchedulableStatus
   {
   public:
-      enum state
-      {
-	  state_running    = 1<<0,
-	  state_ready      = 1<<1,
-	  state_blocked    = 1<<2,
-	  state_future     = 1<<3,
-	  state_terminated = 1<<4
-      };
-      
+    /** \brief This flag describes the actual state of the schedulable
+     *
+     * You can think of this flag as the particular stack in the OS where the
+     * process are placed during their lifetime.  In the OS there are three
+     * main stacks that are Running processes, Read processes, and Blocked
+     * processes. These are emulated in a single list by this flag.
+     */
+    enum state
+    {
+      state_running    = 1<<0,
+      state_ready      = 1<<1,
+      state_blocked    = 1<<2,
+      state_future     = 1<<3,
+      state_terminated = 1<<4
+    };
 
+    /** \brief Object constructor */
     SchedulableStatus(const Schedulable& obj);
+
     //SchedulableStatus(const SchedulableStatus& obj);	//copy constructor
+
+    /** \brief Verify if two instances represents the same situation
+     *
+     * This trivial overloading of the equal operator simply verifies if the
+     * actual represented process is the same, and if the status is also the
+     * same.
+     */
     bool operator==(const SchedulableStatus&) const;
 
-    int 	get_cpu_time_left() const;
-    void 	give_cpu_time(const int& time);	
-    void 	set_last_scheduled(const int& time);	
-    int 	get_last_scheduled() const;
-    state 	get_state() const;
-    void 	set_state(state s);
-    const 	Schedulable* get_schedulable() const;
+    /** \brief Returns the remaining CPU time */
+    int get_cpu_time_left() const;
+
+    /** \brief Decrements cpu time left by this amount until it reaches zero */
+    void give_cpu_time(const int& time);
+
+    /** \brief Sets the time when this process was last scheduled */
+    void set_last_scheduled(const int& time);
+
+    /** \brief Gets the time when this process was last scheduled */
+    int get_last_scheduled() const;
+
+    /** \brief Returns the schedule stack in which this process resides
+     * \see state */
+    state get_state() const;
+
+    /** \brief Sets the state of this process
+     * \see state */
+    void set_state(state s);
+
+    /** \brief Returns a pointer to the schedulable object
+     *
+     * This function returns a pointer to the actual schedable object
+     * represented, along with its status, by this instance.
+     */
+    const Schedulable* get_schedulable() const;
 
   private:
     const Schedulable* _ref;
     int _last;
     int _time_left;
     state _my_state;
-		
   };
-
 }
 
 #endif
-
-