- Commented statistics headers

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

src/backend/concrete_process_statistics.hh

@@ -31,29 +31,34 @@
 namespace sgpem
 {
 	class ConcreteStatistics;
-	
+
-	class ConcreteProcessStatistics : public ProcessStatistics 
+	/**	\brief Represents the statistics of a Process
+
+		This class is a direct subclass of the abstract class ProcessStatistics.
+		For the documentation af all methods refere to it.
+	*/
+	class ConcreteProcessStatistics : public ProcessStatistics
 	{
 		public:
 			friend class ConcreteStatistics;
 			~ConcreteProcessStatistics ();
-			
+
 			int								get_execution_time() const;
 			int								get_execution_progress() const;
 			int								get_total_inactivity() const;
 			int								get_response_time() const;
 			float							get_average_response_time() const;
-			int								get_turn_around() const;			
+			int								get_turn_around() const;
 			int								get_efficiency() const;
 			int								get_resource_usage_time() const;
 			int								get_resource_waitings_time() const;
-			
+
 			const Process* 					get_core() const;
-						
+
 			std::vector<const ThreadStatistics*> 	get_threads_statistics() const;
 		private:
 			ConcreteProcessStatistics (const Process* core, const int& instant);
-			
+
 			const Process* 							_core;
 			float									_average_response_time;
 			std::vector<ConcreteThreadStatistics>	_threads_stats;

src/backend/concrete_simulation_statistics.hh

@@ -30,14 +30,19 @@
 namespace sgpem
 {
 	class ConcreteStatistics;
-	
+
+	/**	\brief Represents the statistics of a Simulation
+
+		This class is a direct subclass of the abstract class SimulationStatistics.
+		For the documentation af all methods refere to it.
+	*/
 	class ConcreteSimulationStatistics : public SimulationStatistics
 	{
-		public:			
+		public:
 			friend class ConcreteStatistics;
-			
+
-			~ConcreteSimulationStatistics();			
+			~ConcreteSimulationStatistics();
-			
+
 			float	get_average_inactivity_time() const ;
 			float 	get_average_execution_progress() const;
 			float	get_average_turn_around() const ;
@@ -47,10 +52,10 @@ namespace sgpem
 			int		get_terminated_threads() const ;
 			float	get_average_processes_throughput() const ;
 			float	get_average_threads_throughput() const ;
-			
+
 		protected:
 			ConcreteSimulationStatistics(const std::vector<ConcreteProcessStatistics>& proc_stats, const int& instant);
-			
+
 			float	_average_inactivity_time ;
 			float	_average_execution_progress ;
 			float	_average_turn_around ;
@@ -61,10 +66,10 @@ namespace sgpem
 			float	_average_processes_throughput ;
 			float	_average_threads_throughput ;
 	};
-}  
+}
+
 
-   
 #endif
 
 
-   
+

src/backend/concrete_statistics.hh

@@ -32,20 +32,24 @@
 
 namespace sgpem
 {
-	class ConcreteStatistics;
 
+	/**	\brief Implements the abstract class Statistics
+
+		This class is a direct subclass of the abstract class Statistics.
+		For the documentation af all methods refere to it.
+	*/
 	class ConcreteStatistics : public Statistics
 	{
 		public:
 			ConcreteStatistics();
-			
+
 			void										calculateStatisticsAt(const int& instant);
-			
+
 			const SimulationStatistics*			 		get_simulation_statistics() const;
-			std::vector<const ProcessStatistics*>		get_process_statistics() const;			
+			std::vector<const ProcessStatistics*>		get_process_statistics() const;
- 		
+
 		private:
-			
+
 			ConcreteSimulationStatistics*				_sim_stats;
 			std::vector<ConcreteProcessStatistics>		_proc_stats;
 	};

src/backend/concrete_thread_statistics.hh

@@ -31,26 +31,32 @@
 namespace sgpem
 {
 	class ConcreteProcessStatistics;
-	
+
+
+	/**	\brief Represents the statistics of a Thread
+
+		This class is a direct subclass of the abstract class ThreadStatistics.
+		For the documentation af all methods refere to it.
+	*/
 	class ConcreteThreadStatistics : public ThreadStatistics
 	{
-		public:		
+		public:
-			friend class ConcreteProcessStatistics;	
+			friend class ConcreteProcessStatistics;
 			~ConcreteThreadStatistics();
-			
+
 			int				get_execution_time() const;
 			int				get_execution_progress() const;
 			int				get_total_inactivity() const;
 			int				get_response_time() const;
-			int				get_turn_around() const;			
+			int				get_turn_around() const;
 			int				get_efficiency() const;
 			int				get_resource_usage_time() const;
 			int				get_resource_waitings_time() const;
-			
+
 			const Thread* 	get_core() const;
-			
+
 			int				get_real_arrival_time() const;	//useful for ProcessStatistics
-		
+
 		private:
 			ConcreteThreadStatistics(const Thread* core, const int& instant);
 			const Thread* 	_core;

src/backend/sgpemv2/process_statistics.hh

@@ -34,6 +34,43 @@
 
 namespace sgpem
 {
+<<<<<<< .mine
+	/**	\brief Represents the statistics of a Process
+
+		Represents the statistics of a Process. This class is created by "Statistics" class
+		and presents only "getters" methods which execute no calculations: they only return the
+		internal results calulated at construction time. To retrieve these results the whole History
+		(until the instant specified through Statistics::calculateStatisticsAt(int)) and the owned threads's
+		statistics are scanned.	For the documentation af all methods refere to class SchedulableStatistics.
+	*/
+	class ProcessStatistics : public SchedulableStatistics
+	{
+		public:
+			~ProcessStatistics();
+
+			int								get_execution_time() const =0;
+			int								get_execution_progress() const =0;
+			int								get_total_inactivity() const =0;
+			int								get_response_time() const =0;
+			virtual float					get_average_response_time() const =0;
+			int								get_turn_around() const =0;
+			int								get_efficiency() const =0;
+			int								get_resource_usage_time() const =0;
+			int								get_resource_waitings_time() const =0;
+
+			const Process*					get_core() const =0;
+
+			/**	\brief Returns the statistics of all owned threads
+				\returns a vector of pointers to the statistics of all owned threads. These statistics are
+							calculated at construction time: this method is only a "getter".
+				\attention Don't delete() these pointers or memory corruption will occur!
+			*/
+			virtual std::vector<const ThreadStatistics*> 	get_threads_statistics() const =0;
+
+		protected:
+			ProcessStatistics();
+	};
+=======
   class ProcessStatistics : public SchedulableStatistics
   {
     public:
@@ -47,6 +84,7 @@ namespace sgpem
     protected:
       ProcessStatistics();
   };
+>>>>>>> .r1204
 }
 
 #endif

src/backend/sgpemv2/schedulable_statistics.hh

@@ -29,34 +29,79 @@
 
 namespace sgpem
 {
+	/**	\brief Represents the statistics of a Schedulable
+
+		Represents the statistics of a Schedulable. This class is created by "Statistics" class
+		and presents only "getters" methods which execute no calculations: they only return the
+		internal results calulated at construction time. To retrieve these results the whole History
+		(until the instant specified through Statistics::calculateStatisticsAt(int)) is scanned.
+	*/
 	class SchedulableStatistics
 	{
-		public:			
+		public:
 			virtual ~SchedulableStatistics();
-			
+
+			/**	\brief Returns the total execution time
+				\returns the number of instants during which the state of the schedulable was "running"
+			*/
 			virtual int	get_execution_time() const =0;
+
+			/**	\brief Returns the percentage of the execution
+				\returns 	the number of instants during which the state of the schedulable was "running"
+							divided by the total running time of the schedulable
+			*/
 			virtual int	get_execution_progress() const =0;
+
+			/**	\brief Returns the total incativity time
+				\returns the number of instants during which the state of the schedulable was "ready" or "blocked"
+			*/
 			virtual int	get_total_inactivity() const =0;
+
+			/**	\brief Returns the response time of the schedulable
+				\returns the number of instants during which the state of the schedulable was "ready" or "blocked"
+							before the first execution instant
+			*/
 			virtual int	get_response_time() const =0;
+
+			/**	\brief Returns the turn-around time of the schedulable
+				\returns the number of instants during which the state of the schedulable was "ready" or "blocked"
+							or "running"
+			*/
 			virtual int	get_turn_around() const =0;
+
+			/**	\brief Returns the percentage of the execution efficiency
+				\returns The percentage of the efficiency. This value is calucated this way: turn_around/execution_time
+			*/
 			virtual int	get_efficiency() const =0;
+
+			/**	\brief Returns the resources usage time of the schedulable
+				\returns the number of instants during which the the schedulable used a resource. If the schedulable
+				used more than one resource a time then this value is increased accordingly.
+			*/
 			virtual int	get_resource_usage_time() const =0;
+
+			/**	\brief Returns the number of instants this schedulable was waiting for a resource to be allocable
+				\returns the number of instants during which the state of the schedulable was "blocked"
+			*/
 			virtual int	get_resource_waitings_time() const =0;
-			
+
+			/**	\brief Returns the Schedulable object these statistics refer to
+				\returns Returns a const pointer to the Schedulable object these statistics refer to
+			*/
 			virtual const Schedulable*		get_core() const =0;
-		
+
 		protected:
-						
+
 			SchedulableStatistics();
-			
+
 			int				_execution_time;
 			int				_execution_progress;
 			int				_total_inactivity;
 			int				_response_time;
 			int				_turn_around;
 			int				_efficiency;
-			int				_resource_usage_time;			
+			int				_resource_usage_time;
-			int				_resource_waitings_time;		
+			int				_resource_waitings_time;
 	};
 }
 

src/backend/sgpemv2/simulation_statistics.hh

@@ -26,27 +26,72 @@
 
 namespace sgpem
 {
+	/**		\brief Represents the statistics about a Simulation
+
+		Represents the statistics about a Simulation. This class is created by "Statistics" class
+		and presents only "getters" methods which execute no calculations: they only return the
+		internal results calulated at construction time.
+	*/
 	class SimulationStatistics
 	{
-		public:			
+		public:
 			virtual ~SimulationStatistics();
-			
+
+			/// \brief Returns the average inactivity time of all processes and threads
+			/// See the documentation of SchedulableStatistics for more informations about this value
+			/// \returns The average inactivity time of all processes and threads
 			virtual float	get_average_inactivity_time() const =0;
+
+			/// \brief Returns the average execution progress of all processes and threads
+			/// See the documentation of SchedulableStatistics for more informations about this value
+			/// \returns The average execution progress of all processes and threads
 			virtual float	get_average_execution_progress() const =0;
+
+			/// \brief Returns the average inactivity time of all processes and threads
+			/// See the documentation of SchedulableStatistics for more informations about this value
+			/// \returns The average inactivity time of all processes and threads
 			virtual float	get_average_turn_around() const =0;
+
+			/// \brief Returns the average response time of all processes and threads
+			/// See the documentation of SchedulableStatistics for more informations about this value
+			/// \returns The average response time of all processes and threads
 			virtual float	get_average_response_time() const =0;
+
+			/// \brief Returns the documentation of SchedulableStatistics for more informations about this value
+			/// See the documentation of SchedulableStatistics for more informations about this value
+			/// \returns The average efficency of all processes and threads
 			virtual float	get_average_efficiency() const =0;
-			virtual int	get_terminated_processes() const =0;
+
-			virtual int	get_terminated_threads() const =0;
+			/// \brief Returns the number of terminated processes
+			/// \returns The number of terminated processes until the instant specified through Statistics::calculateStatisticsAt(int)
+			virtual int		get_terminated_processes() const =0;
+
+			/// \brief Returns the number of terminated threads
+			/// \returns The number of terminated threads until the instant specified through Statistics::calculateStatisticsAt(int)
+			virtual int		get_terminated_threads() const =0;
+
+			/**
+				Returns the average of terminated processes during one instant of scheduling time. The
+				exact formula is: #_terminated_processes / current_instant
+
+				\returns The average of terminated processes during one instant
+			*//
 			virtual float	get_average_processes_throughput() const =0;
+
+			/**
+				Returns the average of terminated threads during one instant of scheduling time. The
+				exact formula is: #_terminated_threads / current_instant
+
+				\returns The average of terminated threads during one instant
+			*//
 			virtual float	get_average_threads_throughput() const =0;
 
-			        
+
 		protected:
-						     
+
 			SimulationStatistics();
-	};        
+	};
-}          
+}
 
 #endif
 

src/backend/sgpemv2/statistics.hh

@@ -31,6 +31,12 @@
 
 namespace sgpem
 {
+	/**		\brief Permits to retrieve the statistics of the current Simulation
+	
+	Permits to retrieve informations about all schedulables and the simulation 
+	at a precise moment in the history
+	
+	*/
 	class Statistics;
 	class ConcreteStatistics;
 
@@ -40,9 +46,41 @@ namespace sgpem
 		virtual ~Statistics() = 0;
 		static Statistics& get_instance();		
 		
+		/**		\brief Calculates the statistics
+		Calculates the statistics until the specified instant which must be equal to
+		or smaller than the current time. This method executes all calculations which
+		can be expensive for the CPU. Each call to this method erases all previously 
+		calculated statistics.
+		
+		\param instant 	The instant until which the History will be examinated to 
+							calculate the statistics
+		*/
 		virtual void									calculateStatisticsAt(const int& instant) = 0;
 		
+		/**	
+		\brief Returns all processes statistics
+					   
+		Returns a copy of all statistics calculated with calculateStatisticsAt() referred
+		to all processes of the environment. If calculateStatisticsAt() has never been
+		called before this call then NULL will be returned.
+		
+		\returns a vector filled with copies of the ProcessStatistics calculated by calculateStatisticsAt()
+					   
+		*/
 		virtual std::vector<const ProcessStatistics*>	get_process_statistics() const = 0;
+			   
+		/**	
+		\brief Returns the simulation statistics
+		
+		Returns a pointer to the statistics of the simulation referred to the instant specified with
+		"calculateStatisticsAt()". If calculateStatisticsAt() has never been called before this call
+		then the NULL pointer will be returned.
+
+	   \attention Don't delete() the returned pointer: this will bring to memory corruption!
+		\returns a pointer to the internal SimulationStatistics object updated by calculateStatisticsAt()
+		\returns the NULL pointer if calculateStatisticsAt() has never been called
+		
+		*/
 		virtual const SimulationStatistics*			get_simulation_statistics() const = 0;
  
 	protected:

src/backend/sgpemv2/thread_statistics.hh

@@ -31,27 +31,35 @@
 
 namespace sgpem
 {
+	/**	\brief Represents the statistics of a Thread
+
+		Represents the statistics of a Thread. This class is created by "Statistics" class
+		and presents only "getters" methods which execute no calculations: they only return the
+		internal results calulated at construction time. To retrieve these results the whole History
+		(until the instant specified through Statistics::calculateStatisticsAt(int)) is scanned.
+		For the documentation af all methods refere to class SchedulableStatistics.
+	*/
   class ThreadStatistics : public SchedulableStatistics
   {
-    public:			
+    public:
       ~ThreadStatistics();
 
       int               get_execution_time() const =0;
       int               get_execution_progress() const =0;
       int               get_total_inactivity() const =0;
       int               get_response_time() const =0;
-      int               get_turn_around() const =0;			
+      int               get_turn_around() const =0;
       int               get_efficiency() const =0;
       int               get_resource_usage_time() const =0;
       int               get_resource_waitings_time() const =0;
 
       const Thread*     get_core() const =0;
-      
+
-      /** \brief Useful for ProcessStatistics 
+      /** \brief Useful for ProcessStatistics
        * \return The first instant at which the thread was first
        * given the processor
        */
-      virtual int       get_real_arrival_time() const =0;	
+      virtual int       get_real_arrival_time() const =0;
 
     protected:
       ThreadStatistics();