- Audited some more files.

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

src/backend/dynamic_schedulable.hh

@@ -27,17 +27,21 @@
 
 namespace sgpem
 {
+
+  /// \brief Desribes the state of a schedulable entity in a particular moment
+  /// of the simulation
+  ///
+  /// Contains part of the information used by the scheduling policies to 
+  /// perform scheduling.
+  /// Objects of subclasses of ::DynamicSchedulable may be created by the system
+  /// via the Scheduler.step_forward() method (which then inserts them into a 
+  /// ::ConcreteEnvironment), or by the user on a resetted ::History by creating
+  /// one of them anew.
+  /// 
+  /// These objects may be destroyed only by resetting an ::History, or via one 
+  /// of its methods.
   class DynamicSchedulable;
 
-  /** \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 DynamicSchedulable are created by the Scheduler and are
-   * destroyed by SimulationStatus if they are linked to it or by the Scheduler.
-   */
   class SG_DLLLOCAL DynamicSchedulable : public virtual Schedulable
   {
   public:
@@ -54,28 +58,117 @@ namespace sgpem
      */
     virtual bool operator==(const Schedulable&) const;
 
+    /// \brief Returns the name of the Schedulable.
+    ///
+    /// Returns the name of the Schedulable.
+    /// It is fetched from the associated ::StaticSchedulable object.
+    /// \return the name of the Schedulable.
     virtual Glib::ustring get_name() const;
 
+    /// \brief Returns the arrival time of the Schedulable.
+    ///
+    /// Returns the arrival time of the Schedulable.
+    /// The arrival time is the instant of the simulation when
+    /// the state of the Schedulable is switched from future to
+    /// ready.
+    ///
+    /// The arrival time is a static (respect to the simulation) property. 
+    /// It is fetched from the associated ::StaticSchedulable object.
+    /// \return the arrival time of the Schedulable.
     virtual unsigned int get_arrival_time() const;
 
+    /// \brief Returns the base priority of the Schedulable.
+    ///
+    /// Returns the base priority of the Schedulable.
+    /// The base priority of a Schedulable is an indicator of the importance of
+    /// the Schedulable. Priority-sensitive policies usually give better services
+    /// to more important Schedulables.
+    ///
+    /// Base priority is summed to the priority push to obtain the current priority
+    /// of the schedulable, which is the real parameter policies read.
+    ///
+    /// The base priority is a static (respect to the simulation) property.
+    /// It is fetched from the associated ::StaticSchedulable object.
+    /// \return the base priority of the Schedulable.
     virtual int get_base_priority() const;
 
+    /// \brief Returns the total required CPU time of the Schedulable.
+    ///
+    /// Returns the total required CPU time of the Schedulable.
+    /// The total required CPU time is the time the Schedulable needs to 
+    /// complete its work.
+    /// 
+    /// When a Schedulable's elapsed CPU time equals the total required CPU time
+    /// its state is set to "terminated". 
+    ///
+    /// The total required CPU time is a static (respect to the simulation) property.
+    /// It is fetched from the associated ::StaticSchedulable object.
+    /// \return the total required CPU time of the Schedulable.
     virtual unsigned int get_total_cpu_time() const;
 
+    /// \brief Returns the current priority push of the Schedulable.
+    ///
+    /// Returns the current priority push of the Schedulable.
+    /// The current priority push of a Schedulable is an indicator of the local 
+    /// importance of the Schedulable. Priority-sensitive policies usually give
+    /// better services to more important Schedulables.
+    ///
+    /// Base priority is summed to the priority push to obtain the current priority
+    /// of the schedulable, which is the real parameter policies read.
+    ///
+    /// The priority push is a dynamic (respect to the simulation) property.
+    /// \return the current priority push of the Schedulable.
     virtual int get_priority_push() const;
 
+    /// \brief Sets the priority push of the Schedulable, returning the old one.
+    ///
+    /// Sets the current priority push of the Schedulable.
+    /// The current priority push of a Schedulable is an indicator of the local 
+    /// importance of the Schedulable. Priority-sensitive policies usually give
+    /// better services to more important Schedulables.
+    ///
+    /// Base priority is summed to the priority push to obtain the current priority
+    /// of the schedulable, which is the real parameter policies read.
+    ///
+    /// The priority push is a dynamic (respect to the simulation) property.
+    /// \param new_value the new push to be set.
+    /// \return the old priority push of the Schedulable.
     virtual int set_priority_push(int new_value = 0);
 
+    /// \brief Returns the current priority of the Schedulable.
+    ///
+    /// Returns the current priority of the Schedulable.
+    /// The current priority of a Schedulable is an indicator of the importance of
+    /// the Schedulable. Priority-sensitive policies usually give better services
+    /// to more important Schedulables.
+    ///
+    /// Base priority is summed to the priority push to obtain the current priority
+    /// of the schedulable, which is the real parameter policies read.
+    ///
+    /// The current priority is a dynamic (respect to the simulation) property.
+    /// \return the dynamic priority of the Schedulable.
     virtual int get_current_priority() const;
 
+    /// \brief Returns the elapsed time of the Schedulable.
+    ///
+    /// Returns the elapsed time of the Schedulable.
+    /// The elapsed time is the amount of time a Schedulable has been running
+    /// until the current instant.
+    ///
+    /// The elapsed time is a dynamic (respect to the simulation) property.
+    /// \return the elapsed time of the Schedulable.
     virtual unsigned int get_elapsed_time() const = 0;
 
-    /** \brief Returns a pointer to the schedulable object
+    /// \brief Returns a pointer to the static schedulable object
-     *
+    /// 
-     * This function returns a reference to the actual schedable object
+    /// This function returns a reference to the actual schedable object
-     * represented, along with its status, by this instance.
+    /// represented, along with its status, by this instance.
-     */
     virtual StaticSchedulable& get_core() = 0;
+
+    /// \brief Returns a constant pointer to the static schedulable object
+    /// 
+    /// This function returns a constant reference to the actual schedable object
+    /// represented, along with its status, by this instance.
     virtual const StaticSchedulable& get_core() const = 0;
 
   private:

src/backend/sgpemv2/module.hh

@@ -1,4 +1,4 @@
-// src/backend/module.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/module.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -30,23 +30,65 @@
 
 namespace sgpem
 {
+
+  /// \brief A link to a loaded DSO object
+  ///
+  /// When a plugin is found, PluginManager::rescan_dirs() tries to load it by
+  /// creating an object of this class.
+  /// The constructor should throw InvalidPluginException if the plugin isn't 
+  /// a valid SGPEMv2 one. This should be handled directly into
+  /// PluginManager::rescan_dirs().
   class Module;
 
   class SG_DLLEXPORT Module : public Glib::Module
   {
   public:
+
+    /// \brief Constructor taking an identifier.
+    /// 
+    /// Constructor taking an identifier.
+    /// \throw InvalidPluginException If the DSO you're trying to load
+    ///  doesn't export a valid SGPEMv2 backend::Plugin interface.
+    /// \param identifier A string with the DSO name without any file-extension 
+    /// suffix. This is retrieved by PluginManager::rescan_dirs().
     Module(const Glib::ustring& identifier) throw(InvalidPluginException);
 
+    /// \brief Enables or disables a plugin
+    ///
+    /// Enables/disables a plugin, calling its on_init()/on_exit() exported 
+    /// functions where appropriate.
+    /// \param enabled whether to enable or disable the module.
     void set_enabled(bool enabled = true);
 
+    /// \brief Returns the name of the module.
+    ///
+    /// Calls Plugin::get_name()
+    /// \return the name of the module.
     Glib::ustring get_name() const;
 
+    /// \brief Returns the author of the module.
+    ///
+    /// Calls Plugin::get_author()
+    /// \return the author of the module.
     Glib::ustring get_author() const;
 
+    /// \brief Returns a description of the module.
+    ///
+    /// Calls Plugin::describe()
+    /// \return a description of the module.
     Glib::ustring describe() const;
 
+    /// \brief Returns the version of the module.
+    ///
+    /// Calls Plugin::get_version()
+    /// \return the version of the module.
     float get_version() const;
 
+    /// \brief Returns whether the module is enabled or disabled.
+    ///
+    /// Enables/disables a plugin, calling its on_init()/on_exit() exported 
+    /// functions where appropriate.
+    /// \param enabled whether to enable or disable the module.
     bool get_enabled() const;
 
   private:
@@ -54,7 +96,12 @@ namespace sgpem
     typedef const char* (*f_ustring)(void);
     typedef float (*f_float)(void);
 
+    /// True if the plugin is enabled, false otherwise
+    ///
     bool _enabled;
+
+    /// A string containing the DSO name, stripped of any file-extension suffix
+    ///
     Glib::ustring _id;
 
     f_void    on_init_ptr;

src/backend/sgpemv2/plugin.hh

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

src/backend/sgpemv2/schedulable.hh

@@ -90,7 +90,7 @@ namespace sgpem
     /// ready.
     ///
     /// The arrival time is a static (respect to the simulation) property.
-    /// \return the arrival time of of the Schedulable.
+    /// \return the arrival time of the Schedulable.
     virtual unsigned int get_arrival_time() const = 0;
 
     /// \brief Returns the elapsed time of the Schedulable.
@@ -100,7 +100,7 @@ namespace sgpem
     /// until the current instant.
     ///
     /// The elapsed time is a dynamic (respect to the simulation) property.
-    /// \return the elapsed time of of the Schedulable.
+    /// \return the elapsed time of the Schedulable.
     virtual unsigned int get_elapsed_time() const = 0;
 
     /// \brief Returns the remaining time of the Schedulable.
@@ -113,7 +113,7 @@ namespace sgpem
     /// and the current elapsed CPU time.
     ///
     /// The remaining time is a dynamic (respect to the simulation) property.
-    /// \return the remaining time of of the Schedulable.
+    /// \return the remaining time of the Schedulable.
     virtual unsigned int get_remaining_time() const;
 
     /// \brief Returns the last aquisition instant of the Schedulable.
@@ -126,7 +126,7 @@ namespace sgpem
     /// Its dual feature is the last release instant.
     ///
     /// The last aquisition instant is a dynamic (respect to the simulation) property.
-    /// \return the last aquisition instant of of the Schedulable.
+    /// \return the last aquisition instant of the Schedulable.
     virtual int get_last_acquisition() const = 0;
 
     /// \brief Returns the last release instant of the Schedulable.
@@ -139,7 +139,7 @@ namespace sgpem
     /// Its dual feature is the last aquisition instant.
     ///
     /// The last release instant is a dynamic (respect to the simulation) property.
-    /// \return the last release instant of of the Schedulable.
+    /// \return the last release instant of the Schedulable.
     virtual int get_last_release() const = 0;
 
     /// \brief Returns the base priority of the Schedulable.
@@ -153,7 +153,7 @@ namespace sgpem
     /// of the schedulable, which is the real parameter policies read.
     ///
     /// The base priority is a static (respect to the simulation) property.
-    /// \return the base priority of of the Schedulable.
+    /// \return the base priority of the Schedulable.
     virtual int get_base_priority() const = 0;
 
     /// \brief Returns the total required CPU time of the Schedulable.
@@ -166,7 +166,7 @@ namespace sgpem
     /// its state is set to "terminated". 
     ///
     /// The total required CPU time is a static (respect to the simulation) property.
-    /// \return the total required CPU time of of the Schedulable.
+    /// \return the total required CPU time of the Schedulable.
     virtual unsigned int get_total_cpu_time() const = 0;
 
     /// \brief Returns the current priority of the Schedulable.
@@ -180,7 +180,7 @@ namespace sgpem
     /// of the schedulable, which is the real parameter policies read.
     ///
     /// The current priority is a dynamic (respect to the simulation) property.
-    /// \return the dynamic priority of of the Schedulable.
+    /// \return the dynamic priority of the Schedulable.
     virtual int get_current_priority() const = 0;
 
     /// \brief Returns the current priority push of the Schedulable.
@@ -194,7 +194,7 @@ namespace sgpem
     /// of the schedulable, which is the real parameter policies read.
     ///
     /// The priority push is a dynamic (respect to the simulation) property.
-    /// \return the current priority push of of the Schedulable.
+    /// \return the current priority push of the Schedulable.
     virtual int get_priority_push() const;
 
     /// \brief Sets the priority push of the Schedulable, returning the old one.
@@ -209,7 +209,7 @@ namespace sgpem
     ///
     /// The priority push is a dynamic (respect to the simulation) property.
     /// \param new_value the new push to be set.
-    /// \return the old priority push of of the Schedulable.
+    /// \return the old priority push of the Schedulable.
     virtual int set_priority_push(int new_value = 0) = 0;
 
     /// \brief Returns the current state of the Schedulable.
@@ -220,7 +220,7 @@ namespace sgpem
     /// states of a schedulable.
     ///
     /// The current state is a dynamic (respect to the simulation) property.
-    /// \return the current state of of the Schedulable.
+    /// \return the current state of the Schedulable.
     virtual state get_state() const = 0;
 
     /// \brief Serializes this entity using a visitor pattern.

src/backend/sgpemv2/simulation_observer.hh

@@ -26,12 +26,26 @@
 namespace sgpem
 {
   class Simulation;
+
+  /// \brief This class instantiates the pattern observer for the target Simulation
+  ///
+  /// A SimulationObserver represents an entity which may register to a Simulation
+  /// to get notifications when the state of the Simulation changes.
   class SimulationObserver;
 
   class SG_DLLEXPORT SimulationObserver
   {
   public:
+    /// \brief Updates the observer with information provided by changed_simulation
+    ///
+    /// This method is called whenever the simulation decides that observers should
+    /// be notified.
+    /// \param changed_simulation the simulation which notifies an update.
     virtual void update(const Simulation& changed_simulation) = 0;
+
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     virtual ~SimulationObserver();
 
   }

src/backend/static_resource.hh

@@ -26,21 +26,56 @@
 
 namespace sgpem
 {
-  class StaticResource;
   class SerializeVisitor;
 
+  /// StaticResource is an object that act for a system resource.
+  /// It has a name, and a number of places.
+  /// 
+  /// The attributes stored in a static entity are static in the sense that 
+  /// they are user-set and no inner mechanism of the Backend component may 
+  /// change these attributes without the user having explicitly asked it.
+  /// 
+  /// This is enforced by not providing any setter method, and by making the 
+  /// copy constructor private. This makes clear that if you want to edit a 
+  /// static entity, you should reset the ::History, remove the old static 
+  /// entity, and create a new dynamic entity for the new static one.
   class StaticResource
   {
   public:
+    /// \brief Constructor taking a defined name and a number of places.
+    ///
+    /// \param name the name of the resource
+    /// \param places the number of places of the resource
     StaticResource(const Glib::ustring& name, unsigned int places = 1);
 
+    /// \brief Returns the name of the Resource.
+    ///
+    /// Returns the name of the Resource.
+    /// \return the name of the Resource.
     Glib::ustring get_name() const;
+
+    /// \brief Modifies the name of the Resource.
+    ///
+    /// Modifies the name of the Resource.
+    /// \param name the new name for the Resource.
+    /// \return the old name of the Resource.
     Glib::ustring set_name(Glib::ustring name);
 
+    /// \brief Returns the number of places of the Resource.
+    ///
+    /// Returns the number of places of the Resource.
+    /// \return the number of places of the Resource.
     unsigned int get_places() const;
+
+    /// \brief Modifies the number of places of the Resource.
+    ///
+    /// Modifies the number of places of the Resource.
+    /// \param name the new number of places for the Resource.
+    /// \return the old number of places of the Resource.
     unsigned int set_places(unsigned int places);
 
   private:
+    /// \brief Private standard copy constructor.
     StaticResource(const StaticResource&);
 
     Glib::ustring _name;

src/backend/static_sub_request.hh

@@ -27,7 +27,21 @@
 
 namespace sgpem
 {
+
+
+  /// \brief Represents the static description of a request.
+  ///
+  /// Represents the static description of a request.
+  /// The attributes stored in a static entity are static in the sense that
+  /// they are user-set and no inner mechanism of the Backend component may
+  /// change these attributes without the user having explicitly asked it.
+  ///
+  /// This is enforced by not providing any setter method, and by making the
+  /// copy constructor private. This makes clear that if you want to edit a
+  /// static entity, you should reset the ::History, remove the old static
+  /// entity, and create a new dynamic entity for the new static one.
   class StaticSubRequest;
+
   class StaticRequest;
   class StaticResource;
 
@@ -36,21 +50,60 @@ namespace sgpem
   public:
     typedef SubRequest::resource_key_t resource_key_t;
 
-    StaticSubRequest(resource_key_t resource_key,
+    /// \brief Constructor taking the resource id, and the length.
-                     unsigned int length);
+    /// 
+    /// Create a StaticSubRequest with assigned StaticResource, 
+    /// for one single places, and for a defined length.
+    /// \param resource_key the id of the requested resource
+    /// \param length the time the resource is needed.
+    StaticSubRequest(resource_key_t resource_key, unsigned int length);
 
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     ~StaticSubRequest();
 
+    /// \brief Returns the id of the requested resource.
+    ///
+    /// Returns the id of the requested resource.
+    /// \return the id of the requested resource.
     resource_key_t get_resource_key() const;
+
+    /// \brief Changes the requested resource.
+    ///
+    /// Changes the requested resource by changing the related id.
+    /// \param resource_key the id of the new requested resource.
+    /// \return the id of the old requested resource.
     resource_key_t set_resource_key(resource_key_t resource_key);
+
+    /// \brief Returns the length of the request.
+    ///
+    /// Returns the length of the request.
+    /// \return the length of the request.
     unsigned int get_length() const;
+
+    /// \brief Modifies the length of the request.
+    ///
+    /// Modifies the length of the request.
+    /// \param length the new lenght of the request.
+    /// \return the old length of the request.
     unsigned int set_length(unsigned int length);
 
   private:
+    /// \brief Private standard copy constructor
+    ///
     StaticSubRequest(const StaticSubRequest&);
+
+    /// \brief Private standard operator assingment.
+    ///
     StaticSubRequest& operator=(const StaticSubRequest&);
 
+    /// The id of the requested resource
+    ///
     resource_key_t _resource_key;
+
+    /// How long (how many time cycles) the resource is needed.
+    ///
     unsigned int _length;
   };
 

src/backend/static_thread.hh

@@ -34,28 +34,117 @@
 namespace sgpem
 {
   class StaticProcess;
-  class StaticThread;
   class StaticRequest;
 
+  /// \brief A StaticThread object is a StaticSchedulable object which describes a 
+  /// thread and offers thread-specific information.
+  /// 
+  /// A StaticThread object stores the invariant characterization of a thread.
+  /// It is used together with the Thread object to fulfill the needs of a 
+  /// PublicSchedulable [PublicThread wannabe] user.
+  /// The attributes stored in a static entity are static in the sense that 
+  /// they are user-set and no inner mechanism of the Backend component may 
+  /// change these attributes without the user having explicitly asked it.
+  /// 
+  /// This is enforced by not providing any setter method, and by making the 
+  /// copy constructor private. This makes clear that if you want to edit a 
+  /// static entity, you should reset the ::History, remove the old static 
+  /// entity, and create a new dynamic entity for the new static one.
+  ///
+  /// One noteworthy thing is the actual meaning of the arrival time of a thread:
+  /// it is the difference between
+  /// 
+  /// the instant of the simulation in which this thread requires the CPU
+  /// for the first time, i.e. the instant at which its creation in the
+  /// operating system is simulated, 
+  /// 
+  /// and
+  /// 
+  /// the instant of the simulation in which the process which owns
+  /// this thread requires the CPU for the first time, i.e. the instant
+  /// at which its creation in the operating system is simulated.
+  class StaticThread;
+
   class StaticThread : public StaticSchedulable
   {
   public:
+
+
+    /// Creates a StaticThread object with definite
+    /// name, father (pointer), total cpu time required, 
+    /// arrival time (default is 0 [zero]) and base priority (default is 0 [zero]).
+    /// 
+    /// \param name the name of the thread
+    /// \param process the father process
+    /// \param cpu_time the total required cpu time
+    /// \param arrival_time the arrival time
+    /// \param base_priority the base priority
     StaticThread(const Glib::ustring& name,
                  StaticProcess& process,
                  unsigned int cpu_time,
                  unsigned int arrival_time = 0,
                  int base_priority = 0);
 
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual destructor.
     virtual ~StaticThread();
 
+    /// \brief Returns the total required CPU time of the Thread.
+    ///
+    /// Returns the total required CPU time of the Thread.
+    /// The total required CPU time is the time the Thread needs to 
+    /// complete its work.
+    /// 
+    /// When a Thread's elapsed CPU time equals the total required CPU time
+    /// its state is set to "terminated". 
+    ///
+    /// The total required CPU time is a static (respect to the simulation) property.
+    /// \return the total required CPU time of the Thread.
     virtual unsigned int get_total_cpu_time() const;
 
+    /// \brief Modifies the total required CPU time of the Thread.
+    ///
+    /// Modifies the total required CPU time of the Thread.
+    /// Returns the old total required CPU time of the Thread.
+    /// The total required CPU time is the time the Thread needs to 
+    /// complete its work.
+    /// 
+    /// When a Thread's elapsed CPU time equals the total required CPU time
+    /// its state is set to "terminated". 
+    ///
+    /// The total required CPU time is a static (respect to the simulation) property.
+    /// \param cpu_time the new amount of total CPU time required by the thread.
+    /// \return the old total required CPU time of the Thread.
     unsigned int set_total_cpu_time(unsigned int cpu_time);
 
+    /// \brief Returns the arrival time of the Thread.
+    ///
+    /// Returns the arrival time of the Thread.
+    /// The arrival time is the instant of the simulation when
+    /// the state of the Thread is switched from future to
+    /// ready.
+    /// @see ::StaticThread.
+    /// \return the arrival time of the Schedulable.
     virtual unsigned int get_arrival_time() const;
 
+    /// \brief Modifies the arrival time of the Thread.
+    ///
+    /// Modifies the arrival time of the Thread.
+    /// The arrival time is the instant of the simulation when
+    /// the state of the Thread is switched from future to
+    /// ready.
+    /// @see ::StaticThread.
+    /// \return the arrival time of the Schedulable.
     virtual unsigned int set_arrival_time(unsigned int arrival_time);
 
+    /// \brief Returns the parent process of the Thread
+    /// 
+    /// This StaticThread object represents the invariant description of a thread.
+    /// That thread belongs to a particular process.
+    /// That process has an associated invariant description.
+    /// This method returns an handle to that description.
+    /// \return the parent process of the Thread
     virtual StaticProcess& get_process();
 
     // Caller can use directly the vector instead that
@@ -65,9 +154,25 @@ namespace sgpem
     virtual std::vector<StaticRequest*>& get_requests();
 
   private:
+
+    /// \brief Private standard copy constructor.
     StaticThread(const StaticThread&);
 
+    /// The difference between
+    /// 
+    /// the instant of the simulation in which this thread requires the CPU
+    /// for the first time, i.e. the instant at which its creation in the
+    /// operating system is simulated, 
+    /// 
+    /// and
+    /// 
+    /// the instant of the simulation in which the process which owns
+    /// this thread requires the CPU for the first time, i.e. the instant
+    /// at which its creation in the operating system is simulated.
     unsigned int _start_time_delta;
+
+    /// The total cpu time required by this thread to terminate. 
+    ///
     unsigned int _required_cpu_time;
     StaticProcess* _process;
     std::vector<StaticRequest*> _static_requests;