- program files documentation

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

plugins/pyloader/src/builtin-policies/rr.py

@@ -1,4 +1,4 @@
-# src/builtin-policies/rr_priority.py - Copyright 2005, 2006, University
+# plugins/pyloader/src/builtin-policies/rr.py - Copyright 2005, 2006, University
 #                            of Padova, dept. of Pure and Applied
 #                            Mathematics
 #

plugins/xmlsave/src/testsuite/test-xml_serializer.cc

@@ -1,4 +1,4 @@
-// src/testsuite/test-history.cc - Copyright 2005, 2006, University
+// plugins/xmlsave/src/testsuite/test-xml_serializer.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -211,7 +211,6 @@ void dumpEnvironment(const Environment& env, ostream &os)
   {
     Resource* r = (*riter).second;
     os << "  resource name: " << r->get_name()
-    /* << " key: " << (*riter).first */
     << " places: " << r->get_places() << endl;
     riter++;
   }
@@ -262,7 +261,7 @@ void dumpEnvironment(const Environment& env, ostream &os)
         {
 
           SubRequest* sr = (*iter3);
-          os << "        sub request: " /* << " resource_key: " << sr->get_resource_key() */;
+          os << "        sub request: ";
 
           Environment::Resources::const_iterator pos = env.get_resources().find(sr->get_resource_key());
           if (pos != env.get_resources().end())

src/backend/concrete_history.cc

@@ -57,6 +57,7 @@ using memory::deletor;
 // ---------------
 // For all you evil-doers on Earth, this is your mighty punishment!
 
+// remove a template object from vector of pointers
 template<typename T>
 static bool deep_remove(std::vector<T*>& v, const T& obj)
 {
@@ -72,6 +73,7 @@ static bool deep_remove(std::vector<T*>& v, const T& obj)
 }
 
 
+// find a template T object into a vector of T pointers
 template<typename T>
 static T* deep_find(const std::vector<T*>& v, const T& obj)
 {

src/backend/concrete_simulation.hh

@@ -1,4 +1,4 @@
-// src/frontend/concrete_simulation.hh - Copyright 2005, 2006, University
+// src/backend/concrete_simulation.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -40,18 +40,62 @@ namespace sgpem
   public:
     ConcreteSimulation();
 
+    /**
+     * \brief Runs the simulation.
+     *
+     * Advances the simulation by one or more steps, depending on the
+     * actual state and on the value set with set_mode().
+     */
     void  run() throw(UserInterruptException, NullPolicyException, MalformedPolicyException);
 
+    /**
+      \brief Pauses a running simulation.
+
+      It is obviously useful only when the advancement mode is continue.
+      Calling again run() will cause the simulation to start from the current
+      simulation step.
+     */
     void  pause();
 
+    /**
+      \brief Jumps the simulation to the specified instant
+      
+      Pauses the simulation and jumps to the specified instant
+      \throw UserInterruptException, NullPolicyException, MalformedPolicyException
+     */
 		void jump_to(History::position p) throw(UserInterruptException, NullPolicyException, MalformedPolicyException);
 
+    /**
+      \brief Stops the simulation.
+
+      Behaves in the same way as pause(), except that the next call to run() 
+      will cause the simulation to start from the beginning.
+     */
     void  stop();
 
+		bool step() throw(UserInterruptException, NullPolicyException, MalformedPolicyException);
+
+    /**
+      \brief This methods allows to change the way the simulation progresses.
+
+      If the input value is 0 (false), the simulation will advance a single time 
+      step for each call to run().
+      If the input value is 1 (true), the simulation will advance contiuosly, 
+      waiting the time defined with set_timer() between each step, until all 
+      processes have terminated, or some error happens. 
+     */
     void  set_mode(mode new_mode);
 
+    /**
+      \return The simulation advancement mode: 0 if step-to-step, 1 if
+      continue.
+     */
     mode  get_mode() const;
 
+    /** 
+      \return The curent simulation state.
+      \see Simulation::state
+     */
     state get_state() const;
 
     /**
@@ -59,22 +103,39 @@ namespace sgpem
      */
     void set_policy(CPUPolicy*) throw(CPUPolicyException);
 
+    /**
+      \brief Setup the resource policy to be used by the system.
+     */
     void set_resource_policy(ResourcePolicy*);
 
+    /**
+      \return A reference to the ConcreteHistory associated with this simulation.
+     */
     ConcreteHistory& get_history();
 
-		const ConcreteHistory& get_history() const;
+    /**
+      \return A const reference to the ConcreteHistory associated with this simulation.
+     */
+    const ConcreteHistory& get_history() const;
 
+    /**
+      \return The CPU policy currently in use.
+     */
     CPUPolicy* get_policy();
+
+    /**
+      \return The resource policy currently in use.
+     */
     ResourcePolicy * get_resource_policy();
 
+
   private:
     state  _state;
     mode   _mode;
     ConcreteHistory _history;
     CPUPolicy* _policy;
     ResourcePolicy* _resource_policy;
-		
+
     bool step() throw(UserInterruptException, NullPolicyException, MalformedPolicyException);
   };
 

src/backend/concrete_simulation_statistics.cc

@@ -36,141 +36,141 @@ ConcreteSimulationStatistics::~ConcreteSimulationStatistics()
 
 ConcreteSimulationStatistics::ConcreteSimulationStatistics(const std::vector<ConcreteProcessStatistics>& proc_stats, const int& instant)
 {
-		_average_inactivity_time = 0;
+  _average_inactivity_time = 0;
-		_average_turn_around = 0;
+  _average_turn_around = 0;
-		_average_response_time = 0;
+  _average_response_time = 0;
-		_average_efficiency = 0;
+  _average_efficiency = 0;
-		_terminated_processes = 0;
+  _terminated_processes = 0;
-		_terminated_threads = 0;
+  _terminated_threads = 0;
-		_average_execution_progress = 0 ;
+  _average_execution_progress = 0 ;
-		_average_processes_throughput = 0;
+  _average_processes_throughput = 0;
-		_average_threads_throughput = 0;
+  _average_threads_throughput = 0;
-	
+  
-	int started_schedulables_count = 0;	//useful for stats thath can be -1
+  int started_schedulables_count = 0;  //useful for stats thath can be -1
-	
+  
-	if (instant == -1)
+  if (instant == -1)
-		return;
+    return;
-	
+  
-	//get infos that don't depend on the Processes statistics
+  //get infos that don't depend on the Processes statistics
-	//but on the current environment:
+  //but on the current environment:
-	
+  
-	//iterate through all processes
+  //iterate through all processes
-	vector<Process*> procs = Simulation::get_instance().get_history().get_environment_at(instant).get_processes();
+  vector<Process*> procs = Simulation::get_instance().get_history().get_environment_at(instant).get_processes();
-	for (unsigned int i=0; i < procs.size(); i++)
+  for (unsigned int i=0; i < procs.size(); i++)
-	{
+  {
-		if (procs[i]->get_state() == Schedulable::state_terminated)
+    if (procs[i]->get_state() == Schedulable::state_terminated)
-			_terminated_processes++;
+      _terminated_processes++;
-		vector<Thread*> threads = procs[i]->get_threads();
+    vector<Thread*> threads = procs[i]->get_threads();
-		//iterate through all threads of this process
+    //iterate through all threads of this process
-		for (unsigned int ii=0; ii < threads.size(); ii++)
+    for (unsigned int ii=0; ii < threads.size(); ii++)
-			if (threads[ii]->get_state() == Schedulable::state_terminated)
+      if (threads[ii]->get_state() == Schedulable::state_terminated)
-				_terminated_threads++;
+        _terminated_threads++;
-	}
+  }
-	
+  
-	//Examinate processes and threads statistics: 
+  //Examinate processes and threads statistics:
-	//SUM all values from processes and threads
+  //SUM all values from processes and threads
-	
+  
-	vector<ConcreteProcessStatistics>::const_iterator p;
+  vector<ConcreteProcessStatistics>::const_iterator p;
-	for (p = proc_stats.begin(); p != proc_stats.end(); p++)
+  for (p = proc_stats.begin(); p != proc_stats.end(); p++)
-	{
+  {
-		
+  
-		if (p->get_response_time() != -1)
+    if (p->get_response_time() != -1)
-		{
+    {
-			started_schedulables_count++;
+      started_schedulables_count++;
-			_average_response_time += p->get_response_time();
+      _average_response_time += p->get_response_time();
-			_average_efficiency += p->get_efficiency();
+      _average_efficiency += p->get_efficiency();
-			_average_inactivity_time += p->get_total_inactivity();
+      _average_inactivity_time += p->get_total_inactivity();
-			_average_turn_around += p->get_turn_around();
+      _average_turn_around += p->get_turn_around();
-			_average_execution_progress += p->get_execution_progress();			
+      _average_execution_progress += p->get_execution_progress();
-		}
+    }
-		
+  
-		//iterate through all threads of this process
+    //iterate through all threads of this process
-		vector<const ThreadStatistics*> thread_stats = p->get_threads_statistics();
+    vector<const ThreadStatistics*> thread_stats = p->get_threads_statistics();
-		vector<const ThreadStatistics*>::const_iterator t;
+    vector<const ThreadStatistics*>::const_iterator t;
-		for (t=thread_stats.begin(); t != thread_stats.end(); t++)
+    for (t=thread_stats.begin(); t != thread_stats.end(); t++)
-			if ((*t)->get_response_time() != -1)
+      if ((*t)->get_response_time() != -1)
-			{
+      {
-				started_schedulables_count++;	
+        started_schedulables_count++;
-				_average_response_time += (*t)->get_response_time();
+        _average_response_time += (*t)->get_response_time();
-				_average_efficiency += (*t)->get_efficiency();
+        _average_efficiency += (*t)->get_efficiency();
-				_average_inactivity_time += (*t)->get_total_inactivity();
+        _average_inactivity_time += (*t)->get_total_inactivity();
-				_average_turn_around += (*t)->get_turn_around();
+        _average_turn_around += (*t)->get_turn_around();
-				_average_execution_progress += (*t)->get_execution_progress();
+        _average_execution_progress += (*t)->get_execution_progress();
-			}
+      }
-				
+  
-	}
+  }
-	
+  
-	//make the AVERAGE and ROUND the values
+  //make the AVERAGE and ROUND the values
-	if (started_schedulables_count != 0)
+  if (started_schedulables_count != 0)
-	{
+  {
-		modff(((_average_response_time / started_schedulables_count) * 100.0f) / 100.0f, &_average_response_time);
+    modff(((_average_response_time / started_schedulables_count) * 100.0f) / 100.0f, &_average_response_time);
-		modff(((_average_efficiency / started_schedulables_count) * 100.0f) / 100.0f, &_average_efficiency);
+    modff(((_average_efficiency / started_schedulables_count) * 100.0f) / 100.0f, &_average_efficiency);
-		modff(((_average_inactivity_time / started_schedulables_count) * 100.0f) / 100.0f, &_average_inactivity_time);
+    modff(((_average_inactivity_time / started_schedulables_count) * 100.0f) / 100.0f, &_average_inactivity_time);
-		modff(((_average_turn_around / started_schedulables_count) * 100.0f) / 100.0f, &_average_turn_around);
+    modff(((_average_turn_around / started_schedulables_count) * 100.0f) / 100.0f, &_average_turn_around);
-		modff(((_average_execution_progress / started_schedulables_count) * 100.0f) / 100.0f, &_average_execution_progress);
+    modff(((_average_execution_progress / started_schedulables_count) * 100.0f) / 100.0f, &_average_execution_progress);
-	}	
+  }
-	if (instant != 0)
+  if (instant != 0)
-	{	
+  {
-		modff((((float)_terminated_processes / (float)instant) * 1000.0f) / 1000.0f, &_average_processes_throughput);
+    modff((((float)_terminated_processes / (float)instant) * 1000.0f) / 1000.0f, &_average_processes_throughput);
-		modff((((float)_terminated_threads	/ (float)instant) * 1000.0f) / 1000.0f, &_average_threads_throughput);
+    modff((((float)_terminated_threads  / (float)instant) * 1000.0f) / 1000.0f, &_average_threads_throughput);
-	}
+  }
 }
-						
+  
 
 
 
-float	
+float  
 ConcreteSimulationStatistics::get_average_inactivity_time() const 
 {
-	return _average_inactivity_time;
+  return _average_inactivity_time;
 }
 
-float	
+float  
 ConcreteSimulationStatistics::get_average_execution_progress() const 
 {
-	return _average_execution_progress;
+  return _average_execution_progress;
 }
 
-float	
+float  
 ConcreteSimulationStatistics::get_average_turn_around() const 
 {
-	return _average_turn_around;
+  return _average_turn_around;
 }
 
-float	
+float  
 ConcreteSimulationStatistics::get_average_response_time() const 
 {
-	return _average_response_time;
+  return _average_response_time;
 }
 
-float	
+float  
 ConcreteSimulationStatistics::get_average_efficiency() const 
 {
-	return _average_efficiency;
+  return _average_efficiency;
 }
 
-int		
+int  
 ConcreteSimulationStatistics::get_terminated_processes() const 
 {
-	return _terminated_processes;
+  return _terminated_processes;
 }
 
-int		
+int  
 ConcreteSimulationStatistics::get_terminated_threads() const 
 {
-	return _terminated_threads;
+  return _terminated_threads;
 }
 
-float	
+float  
 ConcreteSimulationStatistics::get_average_processes_throughput() const 
 {
-	return _average_processes_throughput;
+  return _average_processes_throughput;
 }
 
-float	
+float  
 ConcreteSimulationStatistics::get_average_threads_throughput() const 
 {
-	return _average_threads_throughput;
+  return _average_threads_throughput;
 }
 
 

src/backend/dynamic_thread.hh

@@ -43,45 +43,173 @@ namespace sgpem
   class SG_DLLLOCAL DynamicThread : public DynamicSchedulable, public Thread
   {
   public:
+    /**
+      \brief Constructor.
+      \param core The static counterpart to this object.
+      \param parent The parent process that spawned this thread.
+     */
     DynamicThread(StaticThread* core, DynamicProcess* parent);
+
+    /**
+      \brief Copy constructor.
+      \param other The dynamic thread to clone.
+      \param parent The parent process that spawned this thread.
+     */
     DynamicThread(const DynamicThread &other, DynamicProcess* parent);
+
+    /**
+      \brief Destructor.
+     */
     virtual ~DynamicThread();
 
+    /**
+      \brief Gets the owning process.
+      \return A reference to the DynamicProcess that owns this thread.
+    */
     DynamicProcess& get_process();
 
+    /**
+      \brief Gets this thread's state.
+      \return The current Schedulable::state of this object.
+    */
     state get_state() const;
+
+    /**
+      \brief Sets/gets this thread's state.
+      \param new_state The desired Schedulable::state of this object.
+      \return The previous state.
+    */
     state set_state(state new_state);
 
+    /**
+      \brief Gets the last istant this schedulable has
+        been put in a Running state.
+      
+      \return Current value of last_acquisition.
+     */
     int get_last_acquisition() const;
+    
+    /**
+      \brief Sets/gets the last istant this schedulable
+      has been put in a Running state.
+
+      \param instant New value for last_acquisition.
+      \return Previous value of last_acquisition.
+     */
     void set_last_acquisition(int instant);
 
+    /**
+      \brief Gets the last instant this schedulable has changed its state
+        from running to something else.
+
+      \return Current value of last_release.
+     */
     int get_last_release() const;
+
+    /**
+      \brief Sets/gets the last instant this schedulable has changed
+        its state from running to something else.
+
+      \param instant New value for last_release.
+      \return Previous value of last_release.
+     */
     void set_last_release(int instant);
 
+    /**
+      \brief Gets total running time of this thread.
+
+      \return Current value of _run_for.
+    */
     unsigned int get_elapsed_time() const;
+
+    /**
+      \brief Decreases the schedulable remaining time by one unit.
+    */
     void decrease_remaining_time();
 
-    std::vector<Request*> get_requests();
+    /**
-
+      \brief Serializes this object via the provided visitor.
+      Calls translator->from_thread(this).
+     */
     void serialize(SerializeVisitor& translator) const;
 
+    /**
+      \brief Gets a reference to static counterpart of this object.
+      \return A reference to static counterpart of this object.
+     */
     virtual StaticThread& get_core();
+
+    /**
+      \brief Gets a const reference to static counterpart of this object.
+      \return A const reference to static counterpart of this object.
+     */
     virtual const StaticThread& get_core() const;
 
-    // Does also the job of "add_request" and "remove_request"
+
+
+    /**
+      \brief Returns ::Requests pointers this ::Thread did to some ::Resource.
+        Since C++ (unfortunately) doesn't support covariance for return
+        types when they're contained into std::vector<T>, some black magic
+        (downcasting) will have to happen inside the backend.
+        Does also the job of "add_request" and "remove_request"
+      \return A reference to the DynamicRequests pointers vector.
+     */
+    std::vector<Request*> get_requests();
+
+    /**
+      \brief Returns ::DynamicRequest pointers this ::Thread did to some ::Resource.
+        Since C++ (unfortunately) doesn't support covariance for return
+        types when they're contained into std::vector<T>, some black magic
+        (downcasting) will have to happen inside the backend.
+        Does also the job of "add_request" and "remove_request"
+      \return A reference to the DynamicRequests pointers vector.
+     */
     std::vector<DynamicRequest*>& get_dynamic_requests();
 
   private:
-    // Undefined
+    /**
+      \brief Private copy constructor; avoids public construction of
+      DynamicThread without owning process.
+     */
     DynamicThread(const DynamicThread &other);
 
+    /**
+      \brief Pointer to static counterpart of this object.
+     */
     memory::smart_ptr<StaticThread> _core;
+
+    /**
+      \brief The current state of this thread.
+
+       See Scheduler.step_forward() to know how this state changes.
+     */
     state _state;
+
+    /**
+      \brief Container with this thread's requests.
+     */
     std::vector<DynamicRequest*> _dynamic_requests;
+
+    /**
+      \brief Pointer to this thread parent.
+     */
     DynamicProcess* _parent;
 
+    /**
+      \brief Total running time of this thread
+    */
     unsigned int _ran_for;
+
+    /**
+      \brief The last istant this schedulable has been put in a Running state.
+     */
     int _last_acquisition;
+
+    /**
+      \brief The last instant this schedulable has changed its state
+        from running to something else.
+     */
     int _last_release;
   };
 

src/backend/sgpemv2/simulation.hh

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

src/backend/sgpemv2/string_utils.hh

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