This document presents the Fortran 77 and ANSI C templates for the Portable Timing Routines. The Fortran version of this template was tentatively approved by the user groups participating in the project, at the Second General Ptools meeting. There have been some further discussion about the template and Fortran 77 and ANSI C compliant header files for the library have since been developed. Also a beta version of the implementation is available on the web (Meiko CS2 beta version).

There will be two header files, named "ctimer.h" (for ANSI C) and "ftimer.h" (for Fortran 77) provided with the library for each platform. These files will contain the type declarations, subroutine templates, and manifest constants that will apply to one specific platform. For example, there would be a header file (and perhaps a separate library) for Intel's iPSC 860 and a separate one for the Paragon. The contents of the header files will vary by value, but the names and general meanings will be common to all platforms.

Type definitions:

There will be a type definition for each type of timer value. The quantities represented by these type definitions will be platform specific, although, it is recommended that they be 64 bit values. For platforms that only have 32 bit timer values, it would be inefficient to maintain 64 bits.

ANSI C:

PTR_wall_timer_val

For storing the opaque timer value for wallclock time.

PTR_usr_timer_val

For storing the opaque timer value for user CPU time.

PTR_sys_timer_val

For storing the opaque timer value for system CPU time.

Fortran 77:

Fortran 77 does not have type definitions. Therefore information about the variable types to be used for each platforms will be provided in the header file, e.g. DOUBLE PRECISION, INTEGER*8 etc.

Subroutine templates:

There will be a total of nine subroutine templates. The arguments supplied by or returned to the users will be of type double for ANSI C and DOUBLE PRECISION for Fortran 77. The status codes will be of type int/INTEGER. And all timer values will be of the types created in the type definitions.

• The first three subroutines will initialize/calibrate the values for each type of timer value:

  ANSI C:

  	PTR_Init_wall_timer(opt_wall_ticksize, init_level, wall_stat)
  	PTR_Init_usr_timer(opt_usr_ticksize, init_level, usr_stat)
  	PTR_Init_sys_timer(opt_sys_ticksize, init_level, sys_stat)
  

  Fortran 77:

  	PTR_INIT_WALL_TIMER(opt_wall_ticksize, init_level, wall_stat)
  	PTR_INIT_USR_TIMER(opt_usr_ticksize, init_level, usr_stat)
  	PTR_INIT_SYS_TIMER(opt_sys_ticksize, init_level, sys_stat)
  

  The first argument provides an optional tick period (the nominal tick period or 0 if it has to be calculated), the second specifies the amount of time to be spent for calibration and the third is for the status code.

  The next three acquire the current value of each type of time:

  ANSI C:

  	PTR_Get_wall_time(wall_var)
  	PTR_Get_usr_time(usr_var)
  	PTR_Get_sys_time(sys_var)
  

  Fortran 77:

  	PTR_GET_WALL_TIME (wall_var)        
  	PTR_GET_USR_TIME (usr_var)
  	PTR_GET_SYS_TIME (sys_var)
  

  Each of these subroutines takes one argument - the name of the variable where the value returned by the call will be stored. This argument will be passed by reference to avoid the overhead due to copying.

  The last three calculate the interval elapsed between any two timer values of the same type:

  ANSI C:

  	PTR_Get_wall_interval(wall_var1, wall_var2, wall_secs, wall_stat)
  	PTR_Get_usr_interval(usr_var1, usr_var2, usr_secs, usr_stat)
  	PTR_Get_sys_interval(sys_var1, sys_var2, sys_secs, sys_stat)
  

  Fortran 77:

  	PTR_GET_WALL_INTERVAL (wall_var1, wall_var2, wall_secs, wall_stat)
  	PTR_GET_USR_INTERVAL (usr_var1, usr_var2, usr_secs, usr_stat)
  	PTR_GET_SYS_INTERVAL (sys_var1, sys_var2, sys_secs, sys_stat) 
  

  The first two arguments are the timer values for which the interval has to be calculated. The third argument is the variable that will be used to return the time interval in seconds (e.g., a double precision floating point variable). The status code (the last argument) will be used to return information pertaining to the interval calculated (e.g., ROLLOVER_DETECTED, NOT_AVAILABLE).

Manifest Constants:

There will be 19 manifest constants used in the PTR Library. These will represent error codes, nominal tick period, calibrated tick period, resolution, rollover period and overhead for wall clock, user CPU and system CPU time. For the ANSI C version #defines will be used and PARAMETER statements will be used for the Fortran 77 version.

Nominal Tick period (in secs): value supplied be vendor

 	PTR_WALL_NOM_TICK
 	PTR_USR_NOM_TICK
 	PTR_SYS_NOM_TICK

Calibrated Tick Period (in secs): value set at install time

 	PTR_WALL_CAL_TICK
 	PTR_USR_CAL_TICK
 	PTR_SYS_CAL_TICK

Resolution (in secs): value supplied be vendor

 	PTR_WALL_RESOLUTION
 	PTR_USR_RESOLUTION
 	PTR_SYS_RESOLUTION

Rollover period (in secs): value supplied be vendor

 	PTR_WALL_ROLLOVER
 	PTR_USR_ROLLOVER
 	PTR_SYS_ROLLOVER

Overhead (in secs): value supplied be vendor

 	PTR_WALL_OVERHEAD
 	PTR_USR_OVERHEAD
 	PTR_SYS_OVERHEAD

Error Codes

	PTR_NOT_AVAILABLE	 -1
	PTR_ROLLOVER_DETECTED	 -2
 	PTR_CANNOT_CALIBRATE	 -3
 	PTR_OTHER_ERROR		 -4