- Audited resource_policy_prioirty.hh and others

- Minor corrections to other policies
- Corrected email address in deb distro


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

distro/deb/control-file-v1.0

@@ -6,7 +6,7 @@ Architecture: i386
 Pre-Depends: libstdc++6
 Depends: libgtkmm-2.4-1c2a, libglademm-2.4-1c2a, libxml2 (>= 2.6.10), libcairo, python (>= 2.3)
 Installed-Size: @SIZE@
-Maintainer: Marco Trevisan <evenjin@gmail.com>
+Maintainer: Marco Trevisan <evenjn@gmail.com>
 Provides: sgpemv2
 Description: A graphical process management simulator with educational purposes.
  .

src/backend/sgpemv2/malformed_policy_exception.hh

@@ -1,4 +1,4 @@
-// src/backend/malformed_policy_exception.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/malformed_policy_exception.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -31,11 +31,19 @@
 
 namespace sgpem
 {
+
+  /// \brief An exception signaling a non well-formed script.
+  /// Represents an exception which may be raised to signal that a script which
+  /// was supposed to represent a policy is not well-formed.
   class MalformedPolicyException;
 
   class SG_DLLEXPORT MalformedPolicyException : public CPUPolicyException
   {
   public:
+    /// \brief Constructor taking a message as parameter.
+    ///
+    /// Creates a MalformedPolicyException with an optional detailed message.
+    /// \param msg a message carrying detailed information.
     explicit MalformedPolicyException(const std::string& msg = "");
   };
 } //~ namespace sgpem

src/backend/sgpemv2/resource_policy.hh

@@ -38,51 +38,70 @@ namespace sgpem
 
 namespace sgpem
 {
-  /** \brief It's a Strategy wich stay for a resource allocating algorithm.
-    
-    It implements the related resource allocation policy.
-   */
+
+  /// \brief A resource allocation policy.
+  ///
+  /// A resource allocation policy manages the queues of requests.
+  /// Its purpose is to decide which threads may use the available
+  /// resources first.
   class SG_DLLEXPORT ResourcePolicy
   {
   public:
+
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     virtual ~ResourcePolicy();
 
-    /**
-      \brief Initialize the inner components of the policy.
-
-      Because it's a pure virtual method, must be re-implemented 
-      in concrete derived classes.
-     */
+    /// \brief Initializes the inner components of the policy.
+    ///
+    /// Because it's a pure virtual method, must be re-implemented 
+    /// in concrete derived classes.
     virtual void configure() throw(UserInterruptException) = 0;
 
-    /**
-      \brief Allocate resources to the threads 
-     
-      Because it's a pure virtual method, must be re-implemented 
-      in concrete derived classes.
-     */
+    /// \brief Sorts the subrequest queue.
+    ///
+    /// Because it's a pure virtual method, must be re-implemented 
+    /// in concrete derived classes.
+    ///
+    /// \param environment the environment on which the policy applies.
+    /// \param queue the queue where a subrequest has just been added.
+    /// \param sr the subrequest which has just been added.
     virtual void enforce(Environment& environment, Environment::SubRequestQueue& queue, SubRequest& sr) throw(UserInterruptException) = 0;
 
-    /**
-      \brief 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.
-     */
+    /// \brief Returns a description of the policy.
+    ///
+    /// Because it's a pure virtual method, must be re-implemented 
+    /// in concrete derived classes.
+    /// Returns a description of the policy.
+    /// \return a description of the policy.
     virtual Glib::ustring get_description() const = 0;
 
+    /// \brief Returns the name of the policy.
+    ///
+    /// Because it's a pure virtual method, must be re-implemented 
+    /// in concrete derived classes.
+    /// Returns the name of the policy.
+    /// \return the name of the policy.
     virtual Glib::ustring get_name() const = 0;
 
+    /// \brief Activates the policy.
+    ///
+    /// Because it's a pure virtual method, must be re-implemented 
+    /// in concrete derived classes.
     virtual void activate() = 0;
 
+    /// \brief Deactivates the policy.
+    ///
+    /// Because it's a pure virtual method, must be re-implemented 
+    /// in concrete derived classes.
     virtual void deactivate() = 0;
 
-    /**
-      \brief Gets the parameters related with this policy.
-
-      \return The policy parameters.
-     */
+    /// \brief Returns the parameters used to customize the policy.
+    ///
+    /// Returns the parameters used to customize the policy.
+    /// The user may modify them directly.
+    /// \return the parameters used to customize the policy.
     PolicyParameters& get_parameters();
 
   protected:

src/backend/sgpemv2/resource_policy_fifo.hh

@@ -1,4 +1,4 @@
-// src/backend/resource_policy_fifo.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/resource_policy_fifo.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -21,16 +21,8 @@
 #ifndef RESOURCE_POLICY_FIFO_HH
 #define RESOURCE_POLICY_FIFO_HH 1
 
-#include <sgpemv2/sgpemv2-visibility.hh>
-#include "gettext.h"
-
-#include "glibmm/ustring.h"
-
 #include <sgpemv2/resource_policy.hh>
 
-#include <sgpemv2/policy_parameters.hh>
-#include <sgpemv2/user_interrupt_exception.hh>
-
 namespace sgpem
 {
   class ResourcePolicyFiFo;
@@ -42,6 +34,10 @@ namespace sgpem
   class SG_DLLEXPORT ResourcePolicyFiFo : public ResourcePolicy
   {
   public:
+
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     virtual ~ResourcePolicyFiFo();
 
     /**

src/backend/sgpemv2/resource_policy_lifo.hh

@@ -1,4 +1,4 @@
-// src/backend/resource_policy_lifo.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/resource_policy_lifo.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -21,16 +21,8 @@
 #ifndef RESOURCE_POLICY_LIFO_HH
 #define RESOURCE_POLICY_LIFO_HH 1
 
-#include <sgpemv2/sgpemv2-visibility.hh>
-#include "gettext.h"
-
-#include "glibmm/ustring.h"
-
 #include <sgpemv2/resource_policy.hh>
 
-#include <sgpemv2/policy_parameters.hh>
-#include <sgpemv2/user_interrupt_exception.hh>
-
 namespace sgpem
 {
   class ResourcePolicyLiFo;
@@ -42,6 +34,10 @@ namespace sgpem
   class SG_DLLEXPORT ResourcePolicyLiFo : public ResourcePolicy
   {
   public:
+
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     virtual ~ResourcePolicyLiFo();
 
     /**

src/backend/sgpemv2/resource_policy_priority.hh

@@ -21,62 +21,72 @@
 #ifndef RESOURCE_POLICY_PRIORITY_HH
 #define RESOURCE_POLICY_PRIORITY_HH 1
 
-#include <sgpemv2/sgpemv2-visibility.hh>
-#include "gettext.h"
-
-#include "glibmm/ustring.h"
-
 #include <sgpemv2/resource_policy.hh>
 
-#include <sgpemv2/policy_parameters.hh>
-#include <sgpemv2/user_interrupt_exception.hh>
-
 namespace sgpem
 {
+
+  /// \brief A resource allocation policy which provides a better service
+  /// to higer priority threads.
+  ///
+  /// A resource allocation policy which provides a better service
+  /// to higer priority threads. This policy sorts the request queues
+  /// following the priority of the owners of the requests.
   class ResourcePolicyPriority;
 
-  /** \brief
-  It's a Strategy wich stay for a resource allocating algorithm.
-  It implements the related resource allocation policy.
-  */
   class SG_DLLEXPORT ResourcePolicyPriority : public ResourcePolicy
   {
   public:
+
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     virtual ~ResourcePolicyPriority();
 
-    /**
-      Initialize the inner components of the policy.
-
-      Because it's a pure virtual method, must be re-implemented 
-      in concrete derived classes.
-     */
+    /// \brief Initializes the inner components of the policy.
+    ///
+    /// Does nothing.
     virtual void configure() throw(UserInterruptException);
 
-    /**
-      Mixes the queues.
-     */
+    /// \brief Sorts the subrequest queue letting higher priority threads to be the first ones
+    /// to get the resources.
+    ///
+    /// Sorts the subrequest queue letting higher priority threads to be the first ones
+    /// to get the resources.
+    ///
+    /// \param environment the environment on which the policy applies.
+    /// \param queue the queue where a subrequest has just been added.
+    /// \param sr the subrequest which has just been added.
     virtual void enforce(Environment& environment, Environment::SubRequestQueue& queue, SubRequest& sr) throw(UserInterruptException);
 
-    /**
-      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.
-     */
+    /// \brief Returns a description of the policy.
+    ///
+    /// Returns a description of the policy.
+    /// \return a description of the policy.
     virtual Glib::ustring get_description() const;
 
+    /// \brief Returns the name of the policy.
+    ///
+    /// Returns the name of the policy.
+    /// \return the name of the policy.
     virtual Glib::ustring get_name() const;
 
+
+    /// \brief Activates the policy.
+    ///
+    /// Does nothing.
     virtual void activate();
 
+    /// \brief Deactivates the policy.
+    ///
+    /// Does nothing.
     virtual void deactivate();
 
-    /**
-      Gets the parameters related with this policy.
-
-      \return The policy parameters.
-     */
+    /// \brief Returns the parameters used to customize the policy.
+    ///
+    /// Returns the parameters used to customize the policy.
+    /// The user may modify them directly.
+    /// \return the parameters used to customize the policy.
     PolicyParameters& get_parameters();
 
   protected:

src/backend/sgpemv2/resource_policy_priority_inheritance.hh

@@ -26,14 +26,7 @@ namespace sgpem
   class ResourcePolicyPriorityInheritance;
 }
 
-#include <sgpemv2/sgpemv2-visibility.hh>
-#include "gettext.h"
-
 #include <sgpemv2/resource_policy.hh>
-#include <sgpemv2/policy_parameters.hh>
-#include <sgpemv2/user_interrupt_exception.hh>
-
-#include <glibmm/ustring.h>
 
 namespace sgpem
 {
@@ -44,6 +37,10 @@ namespace sgpem
   class SG_DLLEXPORT ResourcePolicyPriorityInheritance : public ResourcePolicy
   {
   public:
+
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     virtual ~ResourcePolicyPriorityInheritance();
 
     /**

src/backend/sgpemv2/simulation_observer.hh

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