Image Manager (CVCUtilities.dll) 15.0
Performance Timer Functions

Enumerations

enum  TTWACCURACY_LEVEL { TW_ACCURACYLEVELUNKNOWN = 0 , TW_ACCURACYLEVELNORMAL = 1 , TW_ACCURACYLEVELHIGH = 2 }
 Accuracy levels of the high performance timer. Note that the actually achievable accuracy level is system-dependent. More...
 
enum  TTWUNIT { TW_MICROSECONDS = 0 , TW_MILLISECONDS = 1 , TW_SECONDS = 2 }
 Measurement unit selection for the CVB high performance timers. More...
 

Functions

cvbbool_t TWCreate (TIMEWATCH *phTimeWatch)
 Generates a TIMEWATCH object. More...
 
cvbbool_t TWCreateEx (TIMEWATCH *phTimeWatch)
 Generates a TIMEWATCH object. More...
 
cvbbool_t TWDestroy (TIMEWATCH hTimeWatch)
 Releases a TimeWatch object that has been created with TWCreate or TWCreateEx. More...
 
cvbbool_t TWGetAccuracyLevel (TIMEWATCH hTimeWatch, TTWACCURACY_LEVEL *pVal)
 Returns information on the maximum accuracy of a TimeWatch object. More...
 
cvbbool_t TWGetUnit (TIMEWATCH hTimeWatch, TTWUNIT *pVal)
 This function returns the unit of measurement of time durations for a TIMEWATCH object. More...
 
cvbbool_t TWReadStopWatch (TIMEWATCH hTimeWatch, short Index, double *pElapsedTime)
 Reads the timer #Index from a TIMEWATCH object. More...
 
cvbbool_t TWSetUnit (TIMEWATCH hTimeWatch, TTWUNIT Value)
 Sets the time unit of measurement used by the TIMEWATCH object. More...
 
cvbbool_t TWStartStopWatch (TIMEWATCH hTimeWatch, short Index)
 Starts the timer #Index on the TIMEWATCH object. More...
 

Detailed Description

Enumeration Type Documentation

◆ TTWACCURACY_LEVEL

Accuracy levels of the high performance timer. Note that the actually achievable accuracy level is system-dependent.

Enumerator
TW_ACCURACYLEVELUNKNOWN 

Timer accuracy cannot be determined.

TW_ACCURACYLEVELNORMAL 

Timer accuracy is low/normal.

TW_ACCURACYLEVELHIGH 

Timer accuracy is high.

◆ TTWUNIT

enum TTWUNIT

Measurement unit selection for the CVB high performance timers.

The setting determines the units that TWReadStopWatch will use to report the amount of time that has elapsed.

Enumerator
TW_MICROSECONDS 

Microseconds (if possible)

TW_MILLISECONDS 

Milliseconds.

TW_SECONDS 

Seconds.

Function Documentation

◆ TWCreate()

cvbbool_t TWCreate ( TIMEWATCH *  phTimeWatch)

Generates a TIMEWATCH object.

A TIMEWATCH object is used for measuring durations like a stop-watch. A time is measured from calling TWStartStopWatch up to the point TWReadStopWatch is called. A timespan is always measure regarding the last call of TWStartStopWatch. Thus if TWReadStopWatch is called twice after a single call to TWStartStopWatch the times are always measured against the one start time.

This function creates a TIMEWATCH object with millisecond granularity. You can change the granularity by calling TWSetUnit. For the actual precision achievable on your system see the TWGetAccuracyLevel function.

Microsoft Windows Specific (Warning)
The Windows implementation of the TIMEWATCH relies on the QueryPerformanceCounter and QueryPerformanceFrequency functions. These are not safe to use on multi-processor and variable clock systems! Variable clock systems include mobile processors (power save) and processors with a turbo boost feature. Multi-processor systems do not mean multi-core (like e.g. the Intel Core2Duo processors), but multi-processor systems (like e.g. an Intel Dual Xeon system containing two CPUs with a number of cores each).

You can either use the TWCreateEx function to create a safe timer object or disable the clock-changing technologies and/or set the processor affinity of the threads using the function to just one processor.

Linux Specific
This function and TWCreateEx can be used interchangeably as they both return a TIMEWATCH object based on GetTimeOfDay.
Attention
An object created with TWCreate must be released with TWDestroy.
Parameters
[out]phTimeWatchAddress to receive the handle of the newly created TimeWatch object.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TWDestroy, TWGetAccuracyLevel, TWGetUnit, TWSetUnit, TWStartStopWatch, TWReadStopWatch
Sample Code in C++:
#include <iostream>
#include <iomanip>
#include <iCVCUtilities.h>
using namespace std;
void main()
{
// Create time-watch with millisecond granularity
TIMEWATCH hTimeWatch = NULL;
if(!TWCreate(&hTimeWatch))
return; // error
// start timer #0
TWStartStopWatch(hTimeWatch, 0);
// do processing...
// read timer #0
double elapsedTime = 0.0;
TWReadStopWatch(hTimeWatch, 0, &elapsedTime);
TWDestroy(hTimeWatch);
cout << "Processing took " << fixed << setw(2) << elapsedTime << "ms." << endl;
}
cvbbool_t TWReadStopWatch(TIMEWATCH hTimeWatch, short Index, double *pElapsedTime)
Reads the timer #Index from a TIMEWATCH object.
Definition: PerformanceCounter.cpp:346
cvbbool_t TWDestroy(TIMEWATCH hTimeWatch)
Releases a TimeWatch object that has been created with TWCreate or TWCreateEx.
Definition: PerformanceCounter.cpp:253
cvbbool_t TWStartStopWatch(TIMEWATCH hTimeWatch, short Index)
Starts the timer #Index on the TIMEWATCH object.
Definition: PerformanceCounter.cpp:308
cvbbool_t TWCreate(TIMEWATCH *phTimeWatch)
Generates a TIMEWATCH object.
Definition: PerformanceCounter.cpp:119

◆ TWCreateEx()

cvbbool_t TWCreateEx ( TIMEWATCH *  phTimeWatch)

Generates a TIMEWATCH object.

A TIMEWATCH object is used for measuring durations like a stop-watch. A time is measured from calling TWStartStopWatch up to the point TWReadStopWatch is called. A timespan is always measured regarding the last call of TWStartStopWatch. Thus if TWReadStopWatch is called twice after a single call to TWStartStopWatch the times are always measured against the one start time.

This function creates a TIMEWATCH object with millisecond granularity. You can change the granularity by calling TWSetUnit. For the actual precision achievable on your system see the TWGetAccuracyLevel function.

This function creates a TIMEWATCH object based on the file time (Windows) or GetTimeOfDay (Linux). This object normally doesn't achieve microsecond precision on Windows systems, but can be used safely on multi-processor and variable processor-clock systems (see also remarks on TWCreate).

Windows Specific
New or updated applications should use this function to achieve predictable results on any hardware (see TWCreate for details).
Linux Specific
This function returns the same TIMEWATCH object as TWCreate.
Attention
An object created with TWCreate must be released with TWDestroy.
Parameters
[out]phTimeWatchPointer to the address to receive the handle of the newly created TimeWatch object.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TWDestroy, TWGetAccuracyLevel, TWGetUnit, TWSetUnit, TWStartStopWatch, TWReadStopWatch
Sample Code in C++:
#include <iostream>
#include <iomanip>
#include <iCVCUtilities.h>
using namespace std;
void main()
{
// Create time-watch with millisecond granularity
TIMEWATCH hTimeWatch = NULL;
if(!TWCreateEx(&hTimeWatch))
return; // error
// start timer #0
TWStartStopWatch(hTimeWatch, 0);
// do processing...
// read timer #0
double elapsedTime = 0.0;
TWReadStopWatch(hTimeWatch, 0, &elapsedTime);
TWDestroy(hTimeWatch);
cout << "Processing took " << fixed << setw(2) << elapsedTime << "ms." << endl;
}
cvbbool_t TWCreateEx(TIMEWATCH *phTimeWatch)
Generates a TIMEWATCH object.
Definition: PerformanceCounter.cpp:209

◆ TWDestroy()

cvbbool_t TWDestroy ( TIMEWATCH  hTimeWatch)

Releases a TimeWatch object that has been created with TWCreate or TWCreateEx.

Parameters
[in]hTimeWatchHandle of TIMEWATCH object to be destroyed.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TWCreate, TWCreateEx
Sample Code in C++:
For an example see TWCreate.

◆ TWGetAccuracyLevel()

cvbbool_t TWGetAccuracyLevel ( TIMEWATCH  hTimeWatch,
TTWACCURACY_LEVEL pVal 
)

Returns information on the maximum accuracy of a TimeWatch object.

If the returned accuracy is TW_ACCURACYLEVELHIGH you can achieve microsecond resolution with the timer. On TW_ACCURACYLEVELNORMAL only millisecond resolution can be achieved.

Parameters
[in]hTimeWatchHandle of the TimeWatch object to be queried.
[out]pValReceives the maximum accuracy level of a TimeWatch object (see also TTWACCURACY_LEVEL).
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TWCreate, TWCreateEx, TWGetUnit, TWSetUnit, TWStartStopWatch, TWReadStopWatch

◆ TWGetUnit()

cvbbool_t TWGetUnit ( TIMEWATCH  hTimeWatch,
TTWUNIT pVal 
)

This function returns the unit of measurement of time durations for a TIMEWATCH object.

Parameters
[in]hTimeWatchHandle of TimeWatch object to query.
[out]pValMeasurement unit (see TTWUNIT for more information).
Returns
TRUE if succeeded, FALSE otherwise.
Related Topics
TWCreate, TWCreateEx, TWSetUnit, TWReadStopWatch

◆ TWReadStopWatch()

cvbbool_t TWReadStopWatch ( TIMEWATCH  hTimeWatch,
short  Index,
double *  pElapsedTime 
)

Reads the timer #Index from a TIMEWATCH object.

The elapsed time is returned in units defined by TWSetUnit (milliseconds by default).

Attention
The timer must have been started with TWStartStopWatch prior to calling this function.
Parameters
[in]hTimeWatchHandle of TimeWatch object to work on.
[in]IndexIndex of the timer to read.
[out]pElapsedTimeReceives the time duration between the most recent TWStartStopWatch call and the call to this function. The elapsed time is returned in the units defined by TWSetUnit (milliseconds if TWSetUnit has not been called).
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TWCreate, TWCreateEx, TWGetUnit, TWSetUnit, TWStartStopWatch
Sample Code in C++:
For an example see TWCreate.

◆ TWSetUnit()

cvbbool_t TWSetUnit ( TIMEWATCH  hTimeWatch,
TTWUNIT  Value 
)

Sets the time unit of measurement used by the TIMEWATCH object.

Attention
Check the TWGetAccuracyLevel function whether it returns TW_ACCURACYLEVELHIGH, as otherwise the measurement accuracy is limited to milliseconds.
Parameters
[in]hTimeWatchHandle of TimeWatch object to work on.
[in]ValueMeasurement unit (see TTWUNIT for a list of possible values).
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TWCreate, TWCreateEx, TWSetUnit, TWReadStopWatch

◆ TWStartStopWatch()

cvbbool_t TWStartStopWatch ( TIMEWATCH  hTimeWatch,
short  Index 
)

Starts the timer #Index on the TIMEWATCH object.

Parameters
[in]hTimeWatchHandle of TIMEWATCH object to work on.
[in]IndexIndex of the timer to be started.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TWCreate, TWCreateEx, TWGetUnit, TWSetUnit, TWReadStopWatch
Sample Code in C++:
For an example see TWCreate.