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

enum 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] phTimeWatch 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(!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;

}

TWReadStopWatch
cvbbool_t TWReadStopWatch(TIMEWATCH hTimeWatch, short Index, double *pElapsedTime)
Reads the timer #Index from a TIMEWATCH object.
Definition: PerformanceCounter.cpp:346

TWDestroy
cvbbool_t TWDestroy(TIMEWATCH hTimeWatch)
Releases a TimeWatch object that has been created with TWCreate or TWCreateEx.
Definition: PerformanceCounter.cpp:253

TWStartStopWatch
cvbbool_t TWStartStopWatch(TIMEWATCH hTimeWatch, short Index)
Starts the timer #Index on the TIMEWATCH object.
Definition: PerformanceCounter.cpp:308

TWCreate
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] phTimeWatch Pointer 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;

}

TWCreateEx
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] hTimeWatch Handle 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]	hTimeWatch	Handle of the TimeWatch object to be queried.
[out]	pVal	Receives 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]	hTimeWatch	Handle of TimeWatch object to query.
[out]	pVal	Measurement 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]	hTimeWatch	Handle of TimeWatch object to work on.
[in]	Index	Index of the timer to read.
[out]	pElapsedTime	Receives 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]	hTimeWatch	Handle of TimeWatch object to work on.
[in]	Value	Measurement 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]	hTimeWatch	Handle of `TIMEWATCH` object to work on.
[in]	Index	Index 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.


Contact Legal Privacy Statement	Copyright © 2023.
	All rights reserved.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ TTWACCURACY_LEVEL

◆ TTWUNIT

Function Documentation

◆ TWCreate()

◆ TWCreateEx()

◆ TWDestroy()

◆ TWGetAccuracyLevel()

◆ TWGetUnit()

◆ TWReadStopWatch()

◆ TWSetUnit()

◆ TWStartStopWatch()