MODULE timer_services - Timer Services Package (POSIX Compliant)
Description:
This module is a collection of high-level procedures for performing
timing studies upon program sections. The procedures manipulate a
hidden timing object which is dynamically created and deleted by
the tmrCreate and tmrDelete functions. A timer object may measure
intervals in either the day clock or, for most systems, CPU time
systems and, when multiple intervals (as defined by paired
tmrStart and tmrStop function calls) are accumulated, the mean and
standard deviation of the mean are calculated by the tmrCompute
function. The maximum and minimum value of the timing intervals
are obtained from the tmrLimit function. A timer object may be
re-used by calling the tmrClear function to re-initialize it.
Although the standard UNIX systems use an internal clock whose
resolution is specified by the literal CLOCKS_PER_SEC, timing
intervals may, in practice, be determined with greater precision
or intervals shorter than the clock resolution determined by
measuring the interval several times and computing the mean. For
intervals shorter than the clock resolution, the timer operates as
a statistical sampler, measuring the probability that a clock
event occurs within the interval. In order that the measurement be
valid, the process which is being measured must not be synchronous
with the system clock. That is, the process should not call,
either directly or indirectly, any of the system procedures which
would wait upon a clock event.
The functions in this collection are:
Function tmrClear - Clear a timer object
Function tmrCompute - Compute the mean and standard deviation of the
accumulated timing intervals
Function tmrCreate - Create a timer object
Function tmrDelete - Delete a timer object
Function tmrLimit - Get the maximum and minimum timing intervals
Function tmrStart - Start a timing interval
Function tmrStop - End a timing interval
Function tmrClear - Clear a timer object
Description:
This function clears or resets an existing timer object. Following
the clear operation a timer is in the same state as a newly
created object and contains no residue or knowledge of its
previous usage.
Inputs:
id - Timer object identifier
Returns:
TmrStatus - TM_SUCCESS - Normal successful completion
TM_INVARG - Timer object invalid or not defined
SIGNATURE:
TmrStatus tmrClear(const TmrId id)
Function tmrCreate - Create a timer object
Description:
This function creates a new timer object, initializes its internal
state, and returns a unique identifier to the caller. The
identifier is used in subsequent calls to functions in this
package to designate which timer object is to be operated
upon. The timer object is created using dynamic memory
allocation features and, hence, uses a limited resource. It is
essential, when many timers are employed, that unusued ones be
either deleted by the tmrDelete function or reused after first
re-initializing by the tmrClear function. Some systems may not
implement the CPU time (tmmCpu) mode, in which case a
TM_INVARG status is returned.
Inputs:
id - Timer object identifier
mode - Timing mode:
tmmClock - Elapsed time
tmmCpu - CPU time
Returns:
TmrStatus - TM_SUCCESS - Normal successful completion
TM_INVARG - Mode argument is not either tmmClock or
tmmCpu or the mode is not implemented on
this system
TM_NOMEM - Insufficient virtual memory to allocate the
timer object
SIGNATURE:
TmrStatus tmrCreate(TmrId *id,
const TmrMode mode)
Function tmrDelete - Delete a timer object
Description:
This function deletes an existing timer object and returns the memory
occupied by the object to the process dynamic pool. Following
this call, the timer identifier value is invalid.
Inputs:
id - Timer object identifier
Returns:
TmrStatus - TM_SUCCESS - Normal successful completion
TM_INVARG - Timer object invalid or not defined
SIGNATURE:
TmrStatus tmrDelete(const TmrId id)
Function tmrStart - Start a timing interval
Description:
This function starts a timing interval by reading the appropriate
clock (system or CPU). Either the tmrStop or tmrClear function
must be called before another call to tmrStart will be
accepted.
Inputs:
id - Timer object identifier
Returns:
TmrStatus - TM_SUCCESS - Normal successful completion
TM_INVOPR - Timer state is inconsistent with start
operation
TM_INVARG - Timer object invalid or not defined
SIGNATURE:
TmrStatus tmrStart(const TmrId id)
Function tmrStop - End a timing interval
Description:
This function computes a timing interval by reading the appropriate
clock (system or CPU). The elapsed time since the previous
call to tmrStart is calculated and accumulated in an aggregate
elapsed time counter for subsequent statistical calculations
performed by tmrCompute.
Inputs:
id - Timer object identifier
Outputs:
interval - elapsed time (seconds)
Returns:
TmrStatus - TM_SUCCESS - Normal successful completion
TM_INVOPR - Timer state is inconsistent with operation
TM_INVARG - Timer object invalid or not defined
SIGNATURE:
TmrStatus tmrStop(const TmrId id,
float *interval)
Function tmrCompute - Compute the mean and standard deviation of the
accumulated timing intervals
Description:
This function calculates the mean timing interval and the standard
deviation of the mean for a timer object, based on the current
state of the timer object. The object itself is not altered by
this function and its identifier may be used in subsequent
tmrStart/tmrStop function calls to improve the statistical
accuracy of the timing measurement. In the simplest case, when
a single interval has been measured, the value returned in the
standard deviation argument is zero.
Inputs:
id - Timer object identifier
Outputs:
scount - Number of timing intervals
mean - Arithmetic mean of the accumulated timing intervals
seconds)
sigma - Standard deviation of the mean (seconds)
Returns:
TmrStatus - TM_SUCCESS - Normal successful completion
TM_NEGSQR - Negative square root in sigma calculation
TM_INVARG - Timer object invalid or not defined
SIGNATURE:
TmrStatus tmrCompute(const TmrId id,
int *scount,
float *mean,
float *sigma)
Function tmrLimit - Get the maximum and minimum timing intervals
Description:
This function returns the maximum and minimum values timing
intervals. if no timing intervals have been measured the
returned values will be zero.
Inputs:
id - Timer object identifier
Outputs:
min - minimum timing interval (seconds)
max - maximum timing interval (seconds)
Returns:
TmrStatus - TM_SUCCESS - Normal successful completion
TM_INVARG - Timer object invalid or not defined
TM_INVOPR - Timer count is zero
SIGNATURE:
TmrStatus tmrLimit(const TmrId id,
float *min,
float *max)