From 91720fc5f350b9300c19cbcab009922c50170b19 Mon Sep 17 00:00:00 2001 From: kgv Date: Mon, 7 Apr 2014 16:29:04 +0400 Subject: [PATCH] 0024804: OSD_PerfMeter documentation is broken --- src/OSD/OSD_PerfMeter.h | 249 +++++++++++++++++++------------------- src/OSD/OSD_PerfMeter.hxx | 78 ++++++------ 2 files changed, 164 insertions(+), 163 deletions(-) diff --git a/src/OSD/OSD_PerfMeter.h b/src/OSD/OSD_PerfMeter.h index e0d0fa64da..a2a228d9b5 100644 --- a/src/OSD/OSD_PerfMeter.h +++ b/src/OSD/OSD_PerfMeter.h @@ -16,146 +16,147 @@ #ifndef _OSD_PERFMETER_H #define _OSD_PERFMETER_H -/* - Macros for convenient and fast usage of meters. - Define PERF_ENABLE_METERS to make them available. -*/ - +/** + * Macros for convenient and fast usage of meters. + * Define PERF_ENABLE_METERS to make them available. + */ #ifdef PERF_ENABLE_METERS -/* PERF_START_METER - Forces meter MeterName to begin to count by remembering - the current data of timer. - Creates new meter if there is no such meter -*/ -#define PERF_START_METER(_m_name) { \ - static int __iMeter = -1; \ +/** + * @def PERF_START_METER(theMeterName) + * Forces meter MeterName to begin to count by remembering the current data of timer. + * Creates new meter if there is no such meter. + */ +#define PERF_START_METER(_m_name) { \ + static int __iMeter = -1; \ if (__iMeter >= 0) perf_start_imeter (__iMeter); \ else __iMeter = perf_start_meter (_m_name); \ } -/* PERF_STOP_METER - Forces meter MeterName to stop and cumulate the time elapsed - since the start -*/ -#define PERF_STOP_METER(_m_name) { \ - static int __iMeter = -1; \ - if (__iMeter >= 0) perf_stop_imeter (__iMeter); \ - else __iMeter = perf_stop_meter (_m_name); \ +/** + * @def PERF_STOP_METER(theMeterName) + * Forces meter MeterName to stop and cumulate the time elapsed since the start. + */ +#define PERF_STOP_METER(_m_name) { \ + static int __iMeter = -1; \ + if (__iMeter >= 0) perf_stop_imeter (__iMeter); \ + else __iMeter = perf_stop_meter (_m_name); \ } -/* PERF_TICK_METER - Increments the counter of meter MeterName without changing - its state with respect to measurement of time. - Creates new meter if there is no such meter. - It is useful to count the number of enters to a part of code - without wasting a time to measure CPU time. -*/ -#define PERF_TICK_METER(_m_name) { \ - static int __iMeter = -1; \ - if (__iMeter >= 0) perf_tick_imeter (__iMeter); \ - else __iMeter = perf_tick_meter (_m_name); \ +/** + * @def PERF_TICK_METER(theMeterName) + * Increments the counter of meter MeterName without changing its state with respect to measurement of time. + * Creates new meter if there is no such meter. + * It is useful to count the number of enters to a part of code without wasting a time to measure CPU time. + */ +#define PERF_TICK_METER(_m_name) { \ + static int __iMeter = -1; \ + if (__iMeter >= 0) perf_tick_imeter (__iMeter); \ + else __iMeter = perf_tick_meter (_m_name); \ } -/* PERF_CLOSE_METER - Prints out and resets the given meter -*/ +/** + * @def PERF_CLOSE_METER(theMeterName) + * Prints out and resets the given meter. + */ #define PERF_CLOSE_METER(_m_name) perf_close_meter (_m_name); -/* PERF_PRINT_ALL - Prints all existing meters which have been entered at least once - and resets them -*/ -#define PERF_PRINT_ALL { \ - perf_print_all_meters(); \ +/** + * @def PERF_PRINT_ALL + * Prints all existing meters which have been entered at least once and resets them. + */ +#define PERF_PRINT_ALL { \ + perf_print_all_meters(); \ } - #else -#define PERF_TICK_METER(_m_name) -#define PERF_START_METER(_m_name) -#define PERF_STOP_METER(_m_name) -#define PERF_CLOSE_METER(_m_name) -#define PERF_PRINT_ALL + #define PERF_TICK_METER(_m_name) + #define PERF_START_METER(_m_name) + #define PERF_STOP_METER(_m_name) + #define PERF_CLOSE_METER(_m_name) + #define PERF_PRINT_ALL #endif -Standard_EXPORTEXTERNC int perf_init_meter (const char * const MeterName); -/* Creates new counter (if it is absent) identified by - MeterName and resets its cumulative value - Returns : iMeter if OK, -1 if alloc problem -*/ - -Standard_EXPORTEXTERNC int perf_start_meter (const char * const MeterName); -/* Forces meter MeterName to begin to count by remembering - the current data of timer. - Creates new meter if there is no such meter - Returns : iMeter if OK, -1 if no such meter and cannot create a new one -*/ - -Standard_EXPORTEXTERNC int perf_start_imeter (const int iMeter); -/* Forces meter with number iMeter to begin count by remembering - the current data of timer. - Returns : iMeter if OK, -1 if no such meter -*/ - -Standard_EXPORTEXTERNC int perf_stop_meter (const char * const MeterName); -/* Forces meter MeterName to stop and cumulate the time elapsed since the start - Returns : iMeter if OK, -1 if no such meter or it is has not been started -*/ - -Standard_EXPORTEXTERNC int perf_stop_imeter (const int iMeter); -/* Forces meter with number iMeter to stop and cumulate the time - elapsed since the start. - Returns : iMeter if OK, -1 if no such meter or it is has not been started -*/ - -Standard_EXPORTEXTERNC int perf_tick_meter (const char * const MeterName); -/* Increments the counter of meter MeterName without changing - its state with respect to measurement of time. - Creates new meter if there is no such meter - Returns : iMeter if OK, -1 if no such meter and cannot create a new one -*/ - -Standard_EXPORTEXTERNC int perf_tick_imeter (const int iMeter); -/* Increments the counter of meter iMeter without changing - its state with respect to measurement of time. - Returns : iMeter if OK, -1 if no such meter -*/ - -Standard_EXPORTEXTERNC int perf_get_meter (const char * const MeterName, - int * nb_enter, - double * seconds); -/* Tells the time cumulated by meter MeterName and the number - of enters to this meter - Output : *nb_enter, *seconds if the pointers != NULL - Returns : iMeter if OK, -1 if no such meter -*/ - -Standard_EXPORTEXTERNC void perf_close_meter (const char * const MeterName); -/* Prints on stdout the cumulated time and the number of enters - for the specified meter -*/ - -Standard_EXPORTEXTERNC void perf_close_imeter (const int iMeter); -/* Prints on stdout the cumulated time and the number of enters - for the specified meter -*/ - -Standard_EXPORTEXTERNC void perf_print_all_meters (void); -/* Prints on stdout the cumulated time and the number of - enters for each alive meter which have the number of enters > 0. - Resets all meters -*/ - -Standard_EXPORTEXTERNC void perf_destroy_all_meters (void); -/* Deletes all meters and frees memory -*/ - -Standard_EXPORTEXTERNC void perf_print_and_destroy (void); -/* ATTENTION !!! - This func calls both perf_print_all_meters() and perf_destroy_all_meters() - and is called automatically at the end of a program - via system call atexit() -*/ +/** + * Creates new counter (if it is absent) identified by theMeterName and resets its cumulative value + * @return meter global identifier if OK, -1 if alloc problem + */ +Standard_EXPORTEXTERNC int perf_init_meter (const char* const theMeterName); + +/** + * Forces meter theMeterName to begin to count by remembering the current data of timer. + * Creates new meter if there is no such meter. + * @return meter global identifier if OK, -1 if no such meter and cannot create a new one + */ +Standard_EXPORTEXTERNC int perf_start_meter (const char* const theMeterName); + +/** + * Forces meter with number theMeterId to begin count by remembering the current data of timer. + * @return meter global identifier if OK, -1 if no such meter + */ +Standard_EXPORTEXTERNC int perf_start_imeter (const int theMeterId); + +/** + * Forces meter theMeterName to stop and cumulate the time elapsed since the start. + * @return meter global identifier if OK, -1 if no such meter or it is has not been started + */ +Standard_EXPORTEXTERNC int perf_stop_meter (const char* const theMeterName); + +/** + * Forces meter with number theMeterId to stop and cumulate the time elapsed since the start. + * @return meter global identifier if OK, -1 if no such meter or it is has not been started + */ +Standard_EXPORTEXTERNC int perf_stop_imeter (const int theMeterId); + +/** + * Increments the counter of meter theMeterName without changing its state with respect to measurement of time. + * Creates new meter if there is no such meter. + * @return meter global identifier if OK, -1 if no such meter and cannot create a new one + */ +Standard_EXPORTEXTERNC int perf_tick_meter (const char* const theMeterName); + +/** + * Increments the counter of meter theMeterId without changing its state with respect to measurement of time. + * @return meter global identifier if OK, -1 if no such meter + */ +Standard_EXPORTEXTERNC int perf_tick_imeter (const int theMeterId); + +/** + * Tells the time cumulated by meter theMeterName and the number of enters to this meter. + * @param theNbEnter [OUT] number of enters if the pointer != NULL + * @param theSeconds [OUT] seconds if the pointer != NULL + * @return meter global identifier if OK, -1 if no such meter +*/ +Standard_EXPORTEXTERNC int perf_get_meter (const char* const theMeterName, + int* theNbEnter, + double* theSeconds); + +/** + * Prints on stdout the cumulated time and the number of enters for the specified meter. + */ +Standard_EXPORTEXTERNC void perf_close_meter (const char* const theMeterName); + +/** + * Prints on stdout the cumulated time and the number of enters for the specified meter. + */ +Standard_EXPORTEXTERNC void perf_close_imeter (const int theMeterId); + +/** + * Prints on stdout the cumulated time and the number of enters for each alive meter which have the number of enters > 0. + * Resets all meters. + */ +Standard_EXPORTEXTERNC void perf_print_all_meters (void); + +/** + * Deletes all meters and frees memory. + */ +Standard_EXPORTEXTERNC void perf_destroy_all_meters (void); + +/** + * ATTENTION!!! + * This func calls both perf_print_all_meters() and perf_destroy_all_meters() + * and is called automatically at the end of a program via system call atexit(). + */ +Standard_EXPORTEXTERNC void perf_print_and_destroy (void); #endif diff --git a/src/OSD/OSD_PerfMeter.hxx b/src/OSD/OSD_PerfMeter.hxx index a6a73fa1cb..a2372ad72d 100644 --- a/src/OSD/OSD_PerfMeter.hxx +++ b/src/OSD/OSD_PerfMeter.hxx @@ -18,53 +18,53 @@ #include -// This class enables measuring the CPU time between two points of code -// execution, regardless of the scope of these points of code. A meter is -// identified by its name (string of chars). So multiple objects in various -// places of user code may point to the same meter. The results will be -// printed on stdout upon finish of the program. For details see -// OSD_PerfMeter.h - -class OSD_PerfMeter { - - public: - // ---------- PUBLIC METHODS ---------- - - OSD_PerfMeter () : myIMeter(-1) {} - // constructs a void meter (to further call Init and Start) - - OSD_PerfMeter (const char* meter, const unsigned autoStart = 1) - : myIMeter(perf_get_meter(meter,0,0)) { - if (myIMeter < 0) myIMeter = perf_init_meter(meter); - if (autoStart) Start(); - } - // constructs and starts (if autoStart is true) the named meter - - void Init (const char* meter) { - myIMeter = perf_get_meter(meter,0,0); - if (myIMeter < 0) myIMeter = perf_init_meter(meter); +//! This class enables measuring the CPU time between two points of code execution, regardless of the scope of these points of code. +//! A meter is identified by its name (string). So multiple objects in various places of user code may point to the same meter. +//! The results will be printed on stdout upon finish of the program. +//! For details see OSD_PerfMeter.h +class OSD_PerfMeter +{ + +public: + + //! Constructs a void meter (to further call Init and Start) + OSD_PerfMeter() : myIMeter(-1) {} + + //! Constructs and starts (if autoStart is true) the named meter + OSD_PerfMeter (const char* theMeter, + const bool theToAutoStart = true) + : myIMeter (perf_get_meter (theMeter, 0, 0)) + { + if (myIMeter < 0) myIMeter = perf_init_meter (theMeter); + if (theToAutoStart) Start(); } - // prepares the named meter - void Start () const { perf_start_imeter(myIMeter); } - // starts the meter + //! Prepares the named meter + void Init (const char* theMeter) + { + myIMeter = perf_get_meter (theMeter, 0, 0); + if (myIMeter < 0) myIMeter = perf_init_meter (theMeter); + } + + //! Starts the meter + void Start() const { perf_start_imeter(myIMeter); } - void Stop () const { perf_stop_imeter(myIMeter); } - // stops the meter + //! Stops the meter + void Stop() const { perf_stop_imeter(myIMeter); } - void Tick () const { perf_tick_imeter(myIMeter); } - // increments the counter w/o time measurement + //! Increments the counter w/o time measurement + void Tick() const { perf_tick_imeter(myIMeter); } - void Flush () const { perf_close_imeter(myIMeter); } - // outputs the meter data and resets it to initial state + //! Outputs the meter data and resets it to initial state + void Flush() const { perf_close_imeter(myIMeter); } - virtual ~OSD_PerfMeter () { if (myIMeter >= 0) Stop(); } - // assures stopping upon destruction + //! Assures stopping upon destruction + virtual ~OSD_PerfMeter() { if (myIMeter >= 0) Stop(); } - protected: - // ---------- PROTECTED FIELDS ---------- +protected: int myIMeter; + }; -#endif +#endif // OSD_PerfMeter_HeaderFile -- 2.39.5