timing_paths(3)

NAME
timing_paths - timing package

SYNOPSIS
#include <timing_paths.h> #include <histo.h> #include <dtcreg.h> ti_init () ti_create (nEntries, thistie) int nEntries; struct tie *thistie; ti_notetime (thistie, id) struct tie *thistie; long id; ti_postprocess (thistie, twrt) struct tie *thistie; enum timewrt twrt; ti_discoverpaths (thistie, pinfo) struct tie *thistie; struct pths_info *pinfo; ti_stat (thistie, pinfo) struct tie *thistie; struct pths_info *pinfo; ti_destroy (thistie) struct tie *thistie; ti_end ()

DESCRIPTION
This package may be used to time sections of a program. Time values are noted by placing probes in the code at points specified by the user. At each probe location a time value is obtained from a timer. These recorded time values are used to compute the times elapsed between consecutive probes. As an additional feature, for multiple runs of the same program, the package provides first and second order statistics for the elapsed time between consecutive probes. This package only works for timing experiments that take less than 35 minutes to run. The package is used by calling the following routines:

ti_init ()
    initialises the timer.

ti_create ()
    allocates storage for n entries, where n corresponds to the total number of times ti_notetime () is called.

ti_notetime ()
    probes are placed in different sections of the code by calling ti_notetime (). Each probe has to be given a unique id number. In order for the program to function correctly it is necessary that a probe with id 0 is placed at the very beginning of the code being timed.

ti_postprocess ()
    the times obtained from all the ti_notetime () calls are processed by the ti_postprocess () routine. The ti_postprocess () routine can produce the time at each probe with respect to either the very first probe (twrt = BASELINE) or the previous probe (twrt = DELTA).

ti_discoverpaths ()
    for multiple iterations of the code being timed, different paths might be followed each time. A path corresponds to a set of ids beginning with 0, such as (0 1 2, 0 1 4). ti_discoverpaths identifies all the different paths traversed, the number of times each path was traversed and other relevant information.

ti_stat ()
    for each path traversed by the program, ti_stat provides the user with useful statistics (such as mean and standard deviation), for the elapsed time between probes.

ti_destroy ()
    frees the storage used by the package.

ti_end ()
    releases the timer.

DIAGNOSTICS
All successful calls return 0. Negative return values indicate errors. In particular -2 is returned by ti_postprocess if the experiment runs more than 35 minutes.

EXAMPLE

#include <timing_paths.h>
#include <histo.h>
#include <dtcreg.h>
main ()
{
  int i,j, foo, iterations = 10;
  int probes = 3;
  struct tie array_info;
  struct pths_info paths;
  ti_init ();
  ti_create (probes*iterations, &array_info);
  for (i=0; i<iterations; i++)
  {
    ti_notetime (&array_info, 0);
    ti_notetime (&array_info, 1);
    for (j=0; j<10; j++)
    {
      foo = foo +j;
    }
    ti_notetime (&array_info, 2);
  }
  ti_postprocess (&array_info, BASELINE);
  ti_discoverpaths (&array_info,&paths);
  ti_stat (&array_info,&paths);
  ti_destroy ();
  ti_end ();

AUTHOR
Gowthami Rajendran, 1991