- "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,42 +19,42 @@
 // 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):
+			 const int& priority) :
-  _name(name), _arrival_time(arrival), _total_time(total), _priority(priority) 
+  _name(name), _arrival_time(arrival), _total_time(total), _priority(priority)
-{}
+{
-
+}
-
-Schedulable::~Schedulable() 
-{}
 
+Schedulable::~Schedulable()
+{
+}
 
 unsigned int
-Schedulable::get_arrival_time() const 
+Schedulable::get_arrival_time() const
 {
   return _arrival_time;
 }
 
 
-unsigned int 
+unsigned int
-Schedulable::get_total_cpu_time() const 
+Schedulable::get_total_cpu_time() const
 {
   return _total_time;
 }
 
 
-int 
+int
-Schedulable::get_priority() const 
+Schedulable::get_priority() const
 {
   return _priority;
 }
 
-Glib::ustring 			
+Glib::ustring
 Schedulable::get_name() const
 {
   return _name;

src/backend/schedulable.hh

@@ -30,33 +30,59 @@ namespace sgpem
 
   /** \brief An entity that can use the processor
    *
-   *  This abstract class describes an entity that can use the 
+   * This abstract class describes an entity that can use the processor.  It
-   *  processor. It describes the parameters that don't change 
+   * describes the parameters that don't change during a simulation.
-   *  during a simulation.
+   *
-   *  All subclasses are ... (FIXME: teach Luca and Marco what's 
+   * For a reference of a schedulable among its current status see referenced
-   *  the Italian language for, damn them! -- they must have 
+   * class.
-   *  *smoked* mushrooms! :-) ) */
+   *
-  class SG_DLLEXPORT Schedulable 
+   * \see SchedulableStatus
+   */
+  class SG_DLLEXPORT Schedulable
   {
   public:
-    Schedulable(const Glib::ustring& name, const unsigned int& arrival, const unsigned int& total, const int& priority);
+    /** \brief Create a new object with the given parameters */
-    virtual ~Schedulable() = 0;
+    Schedulable(const Glib::ustring& name, const unsigned int& arrival,
-    
+                const unsigned int& total, const int& priority);
-    virtual unsigned int 		get_arrival_time()  const;
+    virtual ~Schedulable();
-    unsigned int                get_total_cpu_time() const;
+
-    int 		      			get_priority() const;
+    /** \brief Returns the arrival time for this process
-    Glib::ustring 				get_name() const;
+     *
-    virtual Glib::ustring		get_type() const = 0;
+     * 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:
     Glib::ustring _name;
     unsigned int _arrival_time;
     unsigned int _total_time;
-    int          _priority;
+    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

@@ -31,47 +31,71 @@
 
 namespace sgpem
 {
-    class SchedulableList;
+  class SchedulableList;
 
-    class SG_DLLEXPORT SchedulableList
+  class SG_DLLEXPORT SchedulableList
-    {
+  {
-    public:
+  public:
-	SchedulableList();
+    SchedulableList();
-	bool 							operator==(const SchedulableList&) const;
+    bool operator==(const SchedulableList&) const;
-	bool 							has_same_objects(const SchedulableList& dx) const;
+    bool has_same_objects(const SchedulableList& dx) const;
 
-	SchedulableStatus* 		top();
+    /** \brief Returns a pointer to the first element
-	SchedulableStatus* 		bottom();
+     *
-	void 							add_at_bottom(const SchedulableStatus&);
+     * This function returns a pointer to the first element, or null if the
-	void 							add_at_top(const SchedulableStatus&);
+     * queue is empty.
-	memory::smart_ptr<sgpem::SchedulableStatus> remove(const unsigned int& position);
+     *
-	bool 							insert_at(const unsigned int&, const unsigned int&);
+     * It is very important not to delete these pointers as their deallocation
-	unsigned int 							size() const;
+     * is managed by the queue.
-	SchedulableStatus*		 		get_item_at(const uint&);
+     */
-	const SchedulableStatus* 		get_item_at(const uint&) const;
+    SchedulableStatus* top();
-	void							clear();
 
-	/** \brief This method swaps the element at positionA with
+    /** \brief Returns a pointer to the last element
-	 * the one at positionB.
+     * \see top
-	 *
+     */
-	 * At the present moment, this function shouldn't throw any
+    SchedulableStatus* bottom();
-	 * 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
-	 * \param positionB The position of the second element to swap
-	 */
-	void swap(unsigned int positionA, unsigned int positionB) throw();
 
-    private:
+    /** \brief Adds an element at the top of the queue */
-	std::list<SchedulableStatus>  _list;
+    void add_at_top(const SchedulableStatus&);
-    };
 
-}//~ namespace sgpem
+    /** \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;
+    SchedulableStatus* get_item_at(const uint&);
+    const SchedulableStatus* get_item_at(const uint&) const;
+    void clear();
+
+    /** \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.
+     *
+     * In the future, this method could throw an OutOfRange exception.
+     *
+     * \param positionA The position of the first element to swap
+     * \param positionB The position of the second element to swap
+     */
+     void swap(unsigned int positionA, unsigned int positionB) throw();
+
+  private:
+    std::list<SchedulableStatus> _list;
+  };
+}
 
 #endif //SCHEDULABLE_LIST_HH
-
-

src/backend/schedulable_status.cc

@@ -1,6 +1,6 @@
-// src/backend/schedulable_status.cc - 	Copyright 2005, 2006, University
+// src/backend/schedulable_status.cc - Copyright 2005, 2006, University
-//               					of Padova, dept. of Pure and Applied
+//               of Padova, dept. of Pure and Applied
-//               					Mathematics
+//               Mathematics
 //
 // This file is part of SGPEMv2.
 //

src/backend/schedulable_status.hh

@@ -1,6 +1,6 @@
-// src/backend/schedulableStatus.hh - 	Copyright 2005, 2006, University
+// src/backend/schedulable_status.hh - Copyright 2005, 2006, University
-//               			of Padova, dept. of Pure and Applied
+//               of Padova, dept. of Pure and Applied
-//               			Mathematics
+//               Mathematics
 //
 // This file is part of SGPEMv2.
 //