- 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

@@ -32,6 +32,11 @@ namespace sgpem
 {
 	class ConcreteStatistics;
 
+	/**	\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:

src/backend/concrete_simulation_statistics.hh

@@ -31,6 +31,11 @@ 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:

src/backend/concrete_statistics.hh

@@ -32,8 +32,12 @@
 
 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:

src/backend/concrete_thread_statistics.hh

@@ -32,6 +32,12 @@ 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:

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,20 +29,65 @@
 
 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:
 			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:

src/backend/sgpemv2/simulation_statistics.hh

@@ -26,19 +26,64 @@
 
 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:
 			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;
 
 

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,6 +31,14 @@
 
 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: