- Audited some files

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

plugins/pyloader/src/ScriptAdapter.py

@@ -1,3 +1,23 @@
+# src/ScriptAdapter.py - Copyright 2005, 2006, University
+#                            of Padova, dept. of Pure and Applied
+#                            Mathematics
+#
+# This file is part of SGPEMv2.
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# SGPEMv2 is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with SGPEMv2; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
 import sys, mutex, thread
 import sgpem
 
@@ -14,7 +34,7 @@ import sgpem
 # adapter = ScriptAdapter(UserPolicyClass)
 # @endcode
 #
-# The user shouldn't care about this class at all.
+# @remarks The user shouldn't care about this class at all.
 class ScriptAdapter :
     ## @var The policy this ScriptAdapter will use for calls
     _policy = None
@@ -23,9 +43,11 @@ class ScriptAdapter :
     # when a threaded function returns
     _ret_val = None
 
-    ## Var Testable syncronization object
+    ## @var Testable syncronization object
     _g_mutex = mutex.mutex()
 
+    ## @var The exception raised from the last called user-defined 
+    # method. It's value is \c None if no exception were raised
     _g_last_exception = None
 
     ## @brief Constructor of ScriptAdapter
@@ -75,6 +97,9 @@ class ScriptAdapter :
 	try:
 	    self._policy.sort_queue(queue)
 	except:
+	    # exception raised in user-defined method,
+	    # save it so the C++ code can tell the
+	    # user what went wrong
 	    self._g_last_exception = sys.exc_value
         self._g_mutex.unlock()
 
@@ -93,6 +118,9 @@ class ScriptAdapter :
         try:
 	    self._ret_val = self._policy.is_preemptive()
 	except:
+	    # exception raised in user-defined method,
+	    # save it so the C++ code can tell the
+	    # user what went wrong
 	    self._g_last_exception = sys.exc_value
         self._g_mutex.unlock()
     
@@ -110,6 +138,9 @@ class ScriptAdapter :
         try:
 	    self._ret_val = self._policy.get_time_slice()
 	except:
+	    # exception raised in user-defined method,
+	    # save it so the C++ code can tell the
+	    # user what went wrong
 	    self._g_last_exception = sys.exc_value
         self._g_mutex.unlock()
     

src/backend/serializer.cc

@@ -1,4 +1,4 @@
-// src/backend/serialize_visitor.cc - Copyright 2005, 2006, University
+// src/backend/serializer.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -26,9 +26,12 @@ using namespace sgpem;
 
 Serializer::Serializer()
 {
+  // automatically register subclasses to the manager
   SerializersGatekeeper::get_instance().register_serializer(this);
 }
 
 Serializer::~Serializer()
-{}
+{
+  // INSPECTOR NOTE: no unregister here?
+}
 

src/backend/sgpemv2/cpu_policy_manager.hh

@@ -21,6 +21,11 @@
 #ifndef CPU_POLICY_MANAGER_HH
 #define CPU_POLICY_MANAGER_HH 1
 
+namespace sgpem
+{
+  class CPUPolicyManager;
+}
+
 #include "config.h"
 
 #include <sgpemv2/cpu_policy.hh>
@@ -30,24 +35,21 @@
 
 namespace sgpem
 {
-  class CPUPolicyManager;
-
   /**
-    CPUPolicyManager is the Abstract Factory for \ref CPUPolicy objects.
+    \brief CPUPolicyManager is the Abstract Factory for 
+    \ref CPUPolicy objects.
   */
   class SG_DLLEXPORT CPUPolicyManager
   {
   public:
     typedef CPUPolicy Policy;
     typedef std::vector<Policy*> Policies;
+    
     /** \brief CPUPolicyManager constructor
      *
-    * Saves ``this'' pointer into the _registered attribute, so it can access
-    * it when requested. This is done so that concrete subclasses can be defined
+    * Registers the \b this pointer to the CPUPoliciesGatekeeper, so it can be accessed
+    * when needed. This is done so that concrete subclasses can be defined
     * even if they are found in external dynamic modules not known at compile time.
-    *
-    * For the moment, just an instance of CPUPolicyManager can be saved. This will
-    * be expanded in next milestones.
     */
     CPUPolicyManager();
 
@@ -56,6 +58,16 @@ namespace sgpem
     virtual const Policies& get_avail_policies() = 0;
 
   protected:
+    /** 
+     * \brief Collects available policies
+     * 
+     * Overriders should implement this method such that it
+     * collects available policies (an operation which may need to be done
+     * at run-time in case user-defined policies are to be supported) 
+     * and puts them inside _policies. The application then assumes this 
+     * method will be called at some time during the initialization of 
+     * the manager (usually inside the constructor).
+     */
     virtual void collect_policies() = 0;
 
     std::vector<CPUPolicy*> _policies;

src/backend/sgpemv2/request.hh

@@ -21,16 +21,19 @@
 #ifndef REQUEST_HH
 #define REQUEST_HH 1
 
-#include "config.h"
-#include <vector>
-
 namespace sgpem
 {
   class Request;
   class SerializeVisitor;
   class SubRequest;
   class Thread;
+}
 
+#include "config.h"
+#include <vector>
+
+namespace sgpem
+{
   class SG_DLLEXPORT Request
   {
   public:

src/jump_to_dialog.cc

@@ -18,8 +18,6 @@
 // along with SGPEMv2; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 
-#include "gettext.h"
-
 #include "jump_to_dialog.hh"
 
 #include <sgpemv2/templates/sequences.tcc>
@@ -28,6 +26,8 @@
 #include <sgpemv2/simulation.hh>
 #include <sgpemv2/resource.hh>
 
+#include "gettext.h"
+
 #include <gtkmm/button.h>
 #include <gtkmm/main.h>
 #include <gtkmm/messagedialog.h>
@@ -81,8 +81,12 @@ JumpToDialog::start()
   Simulation& sim = Simulation::get_instance();
   History&    h   = sim.get_history();
 
+  // start listening to simulation updates
   sim.attach(*this);
+  
+  // remember state of notifications for History
   bool reenable = h.is_notify_enabled();
+  
   try
   {
     if(_target_instant < h.get_size() - 1)
@@ -90,6 +94,8 @@ JumpToDialog::start()
     else
       sim.jump_to(h.get_size() - 1);
 
+    // disable notifications since we could call 
+    // run() a lot of times
     h.set_notify_enabled(false);
     while(h.get_front() <= _target_instant)
     {
@@ -167,9 +173,9 @@ JumpToDialog::on_delete_event(GdkEventAny* event)
 void
 JumpToDialog::update(const Simulation& changed_simulation)
 {
-  unsigned int front = changed_simulation.get_history().get_front();
+  const unsigned int front = changed_simulation.get_history().get_front();
 
-  double percent = std::min(static_cast<double>(front) / _target_instant, 1.0);
+  const double percent = std::min(static_cast<double>(front) / _target_instant, 1.0);
 
   _progress->set_fraction(percent);
 

src/ready_queue_widget.hh

@@ -23,16 +23,20 @@
 
 #include "config.h"
 
-#include <gtkmm/label.h>
-
 #include <sgpemv2/history_observer.hh>
 
+#include <gtkmm/label.h>
+
 namespace sgpem
 {
+  /** 
+   * \brief A custom label widget which displays the ready queue of
+   * the attached History object
+   */
   class ReadyQueueWidget : public HistoryObserver, public Gtk::Label
   {
   public:
-    ReadyQueueWidget(History& history);
+    explicit ReadyQueueWidget(History& history);
     virtual ~ReadyQueueWidget();
 
     virtual void update(const History& changed_history);

src/statistics_container_window.hh

@@ -21,9 +21,14 @@
 #ifndef STATISTICS_CONTAINER_WINDOW_HH
 #define STATISTICS_CONTAINER_WINDOW_HH 1
 
+#include "schedulables_statistics_widget.hh"
+#include "simulation_statistics_widget.hh"
+
 #include "config.h"
 #include "gettext.h"
 
+#include <sgpemv2/simulation.hh>
+
 #include <gtkmm/window.h>
 #include <gtkmm/scrolledwindow.h>
 #include <gtkmm/scrollbar.h>
@@ -32,32 +37,31 @@
 #include <cassert>
 #include <iostream>
 
-#include <sgpemv2/simulation.hh>
-#include "schedulables_statistics_widget.hh"
-#include "simulation_statistics_widget.hh"
+namespace sgpem 
+{
+  /**
+   * \brief Window which displays schedulable-specific and simulation statistics
+   */
+  class StatisticsContainerWindow
+  {
+    public:
+      explicit StatisticsContainerWindow(const std::string& gladefile = GLADEDIR "/statistics-window.glade");
+      virtual ~StatisticsContainerWindow();
 
-namespace sgpem {
+      void                                      make_child(Gtk::Window&);
+      TabularSchedulableStatisticsWidget*   	get_tabular_schedulables_statistics_widget();
+      TabularSimulationStatisticsWidget*   	get_tabular_simulation_statistics_widget();
+      Gtk::Window*                              get_main_window();
+    protected:
 
-
-	class StatisticsContainerWindow
-	{
-	public:
-		StatisticsContainerWindow(const std::string& gladefile = GLADEDIR "/statistics-window.glade");
-		virtual ~StatisticsContainerWindow();
-		
-		void									make_child(Gtk::Window&);
-		TabularSchedulableStatisticsWidget*   	get_tabular_schedulables_statistics_widget();
-		TabularSimulationStatisticsWidget*   	get_tabular_simulation_statistics_widget();
-		Gtk::Window*							get_main_window();
-	protected:
-		
-		Glib::RefPtr<Gnome::Glade::Xml>			_refXml;
-		Gtk::Window*							_main_win;
-		TabularSchedulableStatisticsWidget* 	_tab_sched;
-		TabularSimulationStatisticsWidget* 		_tab_sim;
+      Glib::RefPtr<Gnome::Glade::Xml>           _refXml;
+      Gtk::Window*                              _main_win;
+      TabularSchedulableStatisticsWidget*       _tab_sched;
+      TabularSimulationStatisticsWidget*        _tab_sim;
 
   };
 
 } // ~ namespace sgpem
+
 #endif