Fermi Physics Class Libraries Module: Timer Classes

ZOOM ZOOM

ZMtimer

Timer Classes Sub-package

This mini-package provides several simple timer classes:

This package may be obtained from the following sources:


Description
User Interface
Implementation
Exceptions

Walter Brown, Module Coordinator
Fermilab Physics Class Library Task Force

Comments, questions about getting started, feature needs, and bug/annoyance reports may be sent to zoom-support@fnal.gov or zoom@fnal.gov.

Description

This module provides C++ classes for performing timing studies upon program sections.

A timer object measures and accumulates intervals defined by paired start() and stop() function calls. Such intervals may be based on

  1. the time-of-day clock (use the ZMclkTimer class),
  2. the CPU clock (use the ZMcpuTimer class), or
  3. both (use the ZMdualTimer class).
Each of the above-named classes shares ZMtimer as a common ancestor class.

When multiple intervals are accumulated, the mean and standard deviation of the mean are made available by the member functions mean() and stddev(), respectively. The maximum and minimum values of the timing intervals are available via the max() and min() methods, respectively. A timer object may be re-used by calling the reset() method 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 on intervals shorter than the clock resolution 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 time-of-day clock. That is, the process should not call, either directly or indirectly, any of the system procedures which would wait upon a clock event.

In addition to constructors, the methods in this collection are:

  1. Activation

  2. Elapsed Time

  3. Properties

  4. Statistics

  5. Consolidation

Note 1: since the ZMdualTimer class consists of both a ZMclkTimer and a ZMcpuTimer, methods such as max() and mean() would be ambiguous. Instead, its methods have been given variant names, following the pattern of cpuMax() and clkMean().

Note 2: the += operator requires two timers of identical type. It is strongly recommended that both timers be in the stopped state before this operator is applied, but (in the interests of performance) there is no runtime check to this effect.

User Interface

To use the ZMtimer facilities, a user simply includes the header file:

The code guard for the mini-module is ZMTIMER_H; this symbol may also be used as an external code guard.

Subsequently, the user may instantiate and operate one or more timers, as in the following simple example:

Another example of usage is available via the program testZMtimer.cc, furnished as part of this module.

Implementation

The sole header file needed by the user is ZMtimer/ZMtimer.h, which includes ZMtimer.icc. The remaining implementation is found in ZMtimer.cc.

An auxiliary, environment-dependent, time-of-day class named ZMtime is employed. In addition, a header file ZMutility/ctime is employed to provide a consistent interface to the environment-dependent aspects of timing. This header is available (and recommended) to general users. In particular, certain environments (notably IRIX 6) have certain unfortunate innate dependencies requiring that this header be included in advance of many other system headers in order to obtain correct behavior when used in conjunction with this ZMtimer facility.

Exceptions

The Zoom Exceptions package is employed within ZMtimer to signal erroneous run-time behaviors. The following exception classes are used, all of which generate warning messages:

ZMtimer main page - ZOOM Home Page - Fermilab at Work - Fermilab Home


Walter Brown
Last updated: May 24, 2002.