Taxonomy Categories:
Member Functions:
Interface Category:
Developer Tool Programmer Interface.
Inherits From:
TTest
Inherited By:
TStartStopTimingTest
Purpose:
An abstract base class that represents the tests that measure the time required to perform an operation. Derive TTimingTest to develop performance unit tests.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
This class is a framework class. To use it, derive it and override the TimingTest function, and optionally TimingSetup and TimingCleanup. Derived classes can also override Setup and Cleanup.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TTimingTest ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TTimingTest (const TTimingTest & source)
- TTimingTest ()
- TTimingTest (unsigned long timingCount, unsigned long sampleCount)
- TTimingTest (unsigned long timingCount, unsigned long sampleCount, bool doPCSampling, bool continuallyCalibrate, bool timingIsOn)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
- Copy constructor.
- Default constructor.
- Constructor taking timing and sample counts.
- Constructor taking counts and flags.
Calling Context:
- Called to copy an object.
- Called by the stream-in operators and RunTest.
- Call this function directly.
- Call this function directly.
Parameters:
- const TTimingTest & source -The object to copy.
- Takes no parameters.
- unsigned long timingCount -The number of iterations per sample.
- unsigned long sampleCount -The number of samples per test.
- unsigned long timingCount -The number of samples per test.
- unsigned long sampleCount -The number of samples per test.
- bool doPCSampling -If true, does PC sampling of one sample.
- bool continuallyCalibrate -If true, calibrates each sample.
- bool timingIsOn -If false, does not do timing measurements or loops.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::CopyInfo
virtual void CopyInfo (TDictionaryOf < TStandardText, TText >& infoDictionary) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Framework function that derived classes can override to provide metainformation about themselves.
Calling Context:
Called by Test framework and test logging classes.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetTimingOn
void SetTimingOn (bool timingIsOn)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Enables or disables timing.
Calling Context:
Call this function directly.
Parameters:
- bool timingIsOn -If true, timing loop and measurements are done.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetTimingOn
bool GetTimingOn () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Determines if timing is on.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if timing measurement and loops will be done.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetTimingCount
void SetTimingCount (unsigned long timingCount)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the number of times the TimingTest function is called per sample.
Calling Context:
Call this function directly.
Parameters:
- unsigned long timingCount -The number of times the TimingTest function is called per sample.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetTimingCount
unsigned long GetTimingCount () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Gets the number of times the TimingTest function is called per sample.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The number of times the TimingTest function is called per sample.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetSampleCount
void SetSampleCount (unsigned long sampleCount)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the number of samples taken per test.
Calling Context:
Call this function directly.
Parameters:
- unsigned long sampleCount -The number of samples taken per test.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetSampleCount
unsigned long GetSampleCount () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Gets the number of samples taken per test.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The number of samples taken per test.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetSamplesTaken
unsigned long GetSamplesTaken () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
GetSamplesTaken returns the number of samples actually taken for a full test.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the number of samples actually taken for a full test.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetSamplesDiscarded
unsigned long GetSamplesDiscarded () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the number of samples discarded in the case that automatic timing is on.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the number of samples discarded in the case that automatic timing is on.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::CopySamples
void CopySamples (long & count, double * & theArray) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Takes a pointer to an array and sets it to point to an array which contains the values for each sample taken. It also returns the number of elements of the array.
Calling Context:
Call this function directly.
Parameters:
- long & count -The number of elements that are in theArray.
- double * & theArray -A copy of each sample taken is copied to theArray.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Client owns storage of elements returned in the array.
Member Function: TTimingTest::SetPCSampling
void SetPCSampling (bool doPCSampling)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Controls whether PC sampling is done.
Calling Context:
Call this function directly.
Parameters:
- bool doPCSampling -If true, PC sampling is done for one sample.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetPCSampling
bool GetPCSampling () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Determines whether PC sampling is done.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if PC sampling is done.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetContinualCalibration
void SetContinualCalibration (bool continuallyCalibrate)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Controls whether calibration is done for each sample.
Calling Context:
Call this function directly.
Parameters:
- bool continuallyCalibrate -If true, calibration is done for each sample. Otherwise, calibration is done once before all samples.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetContinualCalibration
bool GetContinualCalibration () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Determines whether calibration is done for each sample.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if calibration is done for each sample. Otherwise, calibration is done once before all samples.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetMaximumAllowedMedianMicroseconds
void SetMaximumAllowedMedianMicroseconds (double timeLimit)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the upper limit for the measured time. If the test takes longer than this value, the test fails.
Calling Context:
Call this function directly.
Parameters:
- double timeLimit -The upper limit for this test to pass.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetCalibratedMedianMicroseconds
double GetCalibratedMedianMicroseconds ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the estimated time for the TimingTest function to execute minus the estimated empty function time, in microseconds. GetCalibratedMedianMicroseconds returns the median of all sample times.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The estimated time for the TimingTest function to execute minus the estimated empty function time, in microseconds. Returns the median of all sample times.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetCalibratedMeanMicroseconds
double GetCalibratedMeanMicroseconds ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the estimated time for the TimingTest function to execute minus the estimated empty function time, in microseconds. GetCalibratedMeanMicroseconds returns the mean of all sample times.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The estimated time for the TimingTest function to execute minus the estimated empty function time, in microseconds. Returns the mean of all sample times.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetRelativeErrorMicroseconds
double GetRelativeErrorMicroseconds () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns a fraction which consists of the half interval of the mean (as returned by GetErrorMicroseconds) over the mean.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a fraction which consists of the half interval of the mean (as returned by GetErrorMicroseconds) over the mean.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetCorrelationMicroseconds
double GetCorrelationMicroseconds () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the correlation between samples.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the correlation between samples.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetErrorMicroseconds
double GetErrorMicroseconds () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the error in the time measured by this test. This error is a 95% confidence interval error.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The error in the time measured by this test.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::ErrorTooLarge
bool ErrorTooLarge () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns true if the relative error from GetRelativeErrorMicroseconds is greater than the tolerance.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if the relative error from GetRelativeErrorMicroseconds is greater than the tolerance.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::CorrelationTooLarge
bool CorrelationTooLarge () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns true if the correlation between samples exceeds the minimum correlation specified by the user.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if true the correlation between samples exceeds the minimum correlation specified by the user.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::Calibrate
void Calibrate ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Measures the empty function time.
Calling Context:
You do not need to call this function. It is called by the Test function.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetClockNowOverhead
double GetClockNowOverhead () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the overhead required to read the clock. This is a measured value (typically around 150 s in v1.0d27). It is used to compute other error tolerances.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The overhead required to read the clock.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetAutomaticSampling
void SetAutomaticSampling (bool doAutomaticSampling)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets a Boolean value that controls whether automatic sampling is done. If the value is true, samples are taken until the error on the measured mean reaches a desired percentage (the tolerance).
Calling Context:
Call this function directly.
Parameters:
- bool doAutomaticSampling -If true, automatic sampling is done.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetAutomaticSampling
bool GetAutomaticSampling () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Gets a Boolean value that controls whether automatic sampling is done. If the value is true, samples are taken until the error on the measured mean reaches a desired percentage (the tolerance).
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if automatic sampling is done.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetAutomaticSampleTolerance
void SetAutomaticSampleTolerance (double tolerance)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the threshold value for automatic sampling. Samples are taken until the error on the measured mean is below this threshold value.
Calling Context:
Call this function directly.
Parameters:
- double tolerance -The threshold value for automatic sampling.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetAutomaticSampleTolerance
double GetAutomaticSampleTolerance () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Gets the threshold value for automatic sampling. Samples are taken until the error on the measured mean is below this threshold value.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Gets the threshold value for automatic sampling.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetMaximumSampleWindows
void SetMaximumSampleWindows (unsigned long maxWindows)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the maximum number of sample windows that are taken, where a sample window consists of n samples and where n is the sample count. If this many sample windows are taken during automatic sampling, testing stops regardless of whether the measurements have converged.
Calling Context:
Call this function directly.
Parameters:
- unsigned long maxWindows -The maximum number of sample windows.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetMaximumSampleWindows
unsigned long GetMaximumSampleWindows () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Gets the maximum number of sample windows that are taken, where a sample window consists of n samples and where n is the sample count. If this many sample windows are taken during automatic sampling, testing stops regardless of whether the measurements have converged.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The maximum number of sample windows.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::SetMinimumSampleCorrelation
void SetMinimumSampleCorrelation (double minSampleCorr)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the minimum correlation between samples for which to post an error.
Calling Context:
Call this function directly.
Parameters:
- double minSampleCorr -The minimum correlation between samples.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetMinimumSampleCorrelation
double GetMinimumSampleCorrelation () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the minimum correlation between samples.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the minimum correlation between samples.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::TimingSetup
virtual void TimingSetup ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Performs any required setup for n consecutive calls to TimingTest, where n is the timing count.
Calling Context:
Called by the framework once per sample.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::TimingTest
virtual void TimingTest ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Does the operation to be timed. Derived classes must override this function even if they override no other. Only this function is timed. This function is called n times consecutively, where n is the timing count.
Calling Context:
Called by the framework n times per sample, where n is the timing count.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::TimingCleanup
virtual void TimingCleanup ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Performs any required cleanup for n consecutive calls to TimingTest, where n is the timing count.
Calling Context:
Called by the framework once per sample.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::Setup
virtual void Setup ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Parses command line arguments.
Calling Context:
Derived classes should call TTimingTest::Setup if they override this member function.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::Test
virtual void Test ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Performs the timing test. Derived classes should not override or call.
Calling Context:
Called by the framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::Cleanup
virtual void Cleanup ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Cleans up storage used internally by TTimingTest.
Calling Context:
Derived classes should call TTimingTest::Cleanup if they override this member function.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::Print
virtual void Print (TTieredTextBuffer &)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Prints information about the object to the given tiered text buffer.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetCurrentTimingCount
unsigned long GetCurrentTimingCount () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the number of the iteration that the timing count loop is currently on. This value may be useful within TimingTest.
Calling Context:
Called in TimingTest.
Parameters:
Return Value:
Returns the number of the iteration that the timing count loop is currently on.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::operator>>=
virtual TStream & operator >>=(TStream & toWhere) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & toWhere -The stream the object is streamed out to.
Return Value:
Returns a reference to the stream the object streams itself out to.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::operator<<=
virtual TStream & operator <<= (TStream & fromWhere)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & fromWhere -The stream the object is streamed in from.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::Hash
virtual long Hash () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Computes and returns the hash value for this object.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the hash value for this object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::operator=
TTimingTest & operator =(const TTimingTest & rhs)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTimingTest::GetMaximumAllowedMedianMicroseconds
double GetMaximumAllowedMedianMicroseconds () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Retrieves the time limit for this timing test.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
Returns the time limit for this timing test.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.