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

- Reorganized the .cc files to match the .hh methods order.


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

src/backend/schedulable.cc

@@ -19,20 +19,20 @@
 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 
 #include "schedulable.hh"
-using namespace sgpem;
 
+using namespace sgpem;
 
 Schedulable::Schedulable(const Glib::ustring& name,
 			 const unsigned int& arrival,
 			 const unsigned int& total,
 			 const int& priority) :
   _name(name), _arrival_time(arrival), _total_time(total), _priority(priority)
-{}
-
+{
+}
 
 Schedulable::~Schedulable()
-{}
-
+{
+}
 
 unsigned int
 Schedulable::get_arrival_time() const

src/backend/schedulable.hh

@@ -30,22 +30,51 @@ namespace sgpem
 
   /** \brief An entity that can use the processor
    *
-   *  This abstract class describes an entity that can use the 
-   *  processor. It describes the parameters that don't change 
-   *  during a simulation.
-   *  All subclasses are ... (FIXME: teach Luca and Marco what's 
-   *  the Italian language for, damn them! -- they must have 
-   *  *smoked* mushrooms! :-) ) */
+   * This abstract class describes an entity that can use the processor.  It
+   * describes the parameters that don't change during a simulation.
+   *
+   * For a reference of a schedulable among its current status see referenced
+   * class.
+   *
+   * \see SchedulableStatus
+   */
   class SG_DLLEXPORT Schedulable
   {
   public:
-    Schedulable(const Glib::ustring& name, const unsigned int& arrival, const unsigned int& total, const int& priority);
-    virtual ~Schedulable() = 0;
+    /** \brief Create a new object with the given parameters */
+    Schedulable(const Glib::ustring& name, const unsigned int& arrival,
+                const unsigned int& total, const int& priority);
+    virtual ~Schedulable();
 
+    /** \brief Returns the arrival time for this process
+     *
+     * The arrival time of a process is the number of time units, starting
+     * from instant zero, at which the process is added on the queue.
+     */
     virtual unsigned int get_arrival_time() const;
+
+    /** \brief Returns the amount of CPU time this process is going to require */
     unsigned int get_total_cpu_time() const;
+
+    /** \brief Returns the priority of this process
+     *
+     * The priority of a process is a number assigned to it when it is
+     * spawned, and never changes for its lifetime.
+     */
     int get_priority() const;
+
+    /** \brief Returns a string representing this object
+     *
+     * The name of a process is a human readable string assigned to it by the
+     * user, that allows it to be quickly recognized.
+     */
     Glib::ustring get_name() const;
+
+    /** \brief Returns the type of the process
+     *
+     * This is an abstract method as the schedulable type is defined by the
+     * concrete process, thread, or any other schedulable entity.
+     */
     virtual Glib::ustring get_type() const = 0;
 
   private:
@@ -53,10 +82,7 @@ namespace sgpem
     unsigned int _arrival_time;
     unsigned int _total_time;
     int _priority;
-	
   };
-    
 }
 
 #endif
-

src/backend/schedulable_list.cc

@@ -1,4 +1,4 @@
-// src/frontend/schedulable_list.cc - Copyright 2005, 2006, University
+// src/backend/schedulable_list.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -24,18 +24,10 @@ using namespace sgpem;
 using namespace std;
 using namespace memory;
 
-
 SchedulableList::SchedulableList()
 {
 }
 
-/**
-	Returns a pointer to the first element. If the queue is empty the NULL pointer will
-	be returned.
-
-	DON'T call delete on the returned pointer! Its destruction is managed by the queue.
- */
-
 SchedulableStatus*
 SchedulableList::top()
 {
@@ -44,13 +36,6 @@ SchedulableList::top()
 	return &_list.front();
 }
 
-/**
-	Returns a pointer to the last element. If the queue is empty the NULL pointer will
-	be returned.
-
-	DON'T call delete on the returned pointer! Its destruction is managed by the queue.
-*/
-
 SchedulableStatus*
 SchedulableList::bottom()
 {
@@ -99,6 +84,11 @@ SchedulableList::size() const
 	return _list.size();
 }
 
+void
+SchedulableList::add_at_top(const SchedulableStatus& ss)
+{
+	_list.push_front(ss);
+}
 
 void
 SchedulableList::add_at_bottom(const SchedulableStatus& ss)
@@ -106,19 +96,6 @@ SchedulableList::add_at_bottom(const SchedulableStatus& ss)
 	_list.push_back(ss);
 }
 
-void
-SchedulableList::add_at_top(const SchedulableStatus& ss)
-{
-	_list.push_front(ss);
-}
-
-/**
-	Removes an element from the list. Returns a smart pointer a copy of it or to NULL if
-	"position" is out of range.
-
-	Ex.	remove(0);			removes the top of the list
-	Ex. remove(size()-1)	removes the bottom of the list
-*/
 smart_ptr<SchedulableStatus>
 SchedulableList::remove(const uint& position)
 {
@@ -235,4 +212,3 @@ SchedulableList::swap(unsigned int positionA, unsigned int positionB) throw()
 	*i1 = *i2;
 	*i2 = temp;
 }
-

src/backend/schedulable_list.hh

@@ -40,10 +40,36 @@ namespace sgpem
     bool operator==(const SchedulableList&) const;
     bool has_same_objects(const SchedulableList& dx) const;
 
+    /** \brief Returns a pointer to the first element
+     *
+     * This function returns a pointer to the first element, or null if the
+     * queue is empty.
+     *
+     * It is very important not to delete these pointers as their deallocation
+     * is managed by the queue.
+     */
     SchedulableStatus* top();
+
+    /** \brief Returns a pointer to the last element
+     * \see top
+     */
     SchedulableStatus* bottom();
-	void 							add_at_bottom(const SchedulableStatus&);
+
+    /** \brief Adds an element at the top of the queue */
     void add_at_top(const SchedulableStatus&);
+
+    /** \brief Adds an element at the end of the queue */
+    void add_at_bottom(const SchedulableStatus&);
+
+    /** \brief Removes */
+/**
+	Removes an element from the list. Returns a smart pointer a copy of it or to NULL if
+	"position" is out of range.
+
+	Ex.	remove(0);			removes the top of the list
+	Ex. remove(size()-1)	removes the bottom of the list
+*/
+
     memory::smart_ptr<sgpem::SchedulableStatus> remove(const unsigned int& position);
     bool insert_at(const unsigned int&, const unsigned int&);
     unsigned int size() const;
@@ -51,14 +77,15 @@ namespace sgpem
     const SchedulableStatus* get_item_at(const uint&) const;
     void clear();
 
-	/** \brief This method swaps the element at positionA with
-	 * the one at positionB.
+    /** \brief This method swaps two elements given their list positions
+     *
+     * At the present moment, this function shouldn't throw any exception, but
+     * just do nothing when the parameters don't make sense (e.g. one of the
+     * positions is outside range [0,this.size()]).
+     *
+     * However, it should work the same either if positionA is greater than or
+     * less than positionB.
      *
-	 * At the present moment, this function shouldn't throw any
-	 * exception, but just do nothing when the parameters don't
-	 * make sense (e.g. positionB > this.size()).
-	 * However, it should work the same either if positionA is greater
-	 * than or less than positionB.
      * In the future, this method could throw an OutOfRange exception.
      *
      * \param positionA The position of the first element to swap
@@ -69,9 +96,6 @@ namespace sgpem
   private:
     std::list<SchedulableStatus> _list;
   };
-
-}//~ namespace sgpem
+}
 
 #endif //SCHEDULABLE_LIST_HH
-
-

src/backend/schedulable_status.hh

@@ -1,4 +1,4 @@
-// src/backend/schedulableStatus.hh - 	Copyright 2005, 2006, University
+// src/backend/schedulable_status.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //