In early summer, Gary Brooks of Convex suggested that four issues still needed to be dealt with. Each is described below. Responses from other committee members are appended.

(1) Replace manifest constants with runtime values

Current situation:

Currently there are fifteen manifest constants that are used to statically characterize the (three)) timers.

Proposal:

Replace these manifest constants with runtime (timer characterization) functions.

Rationale:

Manifest constants have been a source of heated discussions from the beginning and have given rise to several problems including the following:

• Manifest constants are not suited very well for calibration. Since they are constants, they cannot be replaced by calibrated values.
• This gave rise to the split of manifest constants into nominal and calibrated.
• But the calibrated values are still constants and not changeable at run-time. This means that the calibration has to be done at compile or install-time and not at run-time.
• Restricting calibration to install-time means that one cannot run an executable linked with a PTR library from one machine on another binary-compatible machine with different timer characteristics.
• Compile or install-time calibration also means that a multi-threaded application cannot spread across nodes with different timer characteristics.
• The nominal values are meaningless for machines for which the timer characteristics can be determined only at run-time or boot-time.
• The nominal values are also meaningless for machines from vendors who support different resolutions.

However, two of the reasons for having the manifest constants in the first place still remain valid:

• to provide enough information to the user about timers
• to provide efficient access to such information

We can satisfy the above functional requirements by using run-time values to characterize the timers. This will also

• eliminate the need for two types of characterizations (nominal and calibrated) for the timers.
• allow run-time, install-time and compile-time calibrations
• provide more accurate information to the user
• allow portable use of PTR across binary-compatible machines
• allow use of PTR on a multi-node machine with multiple timers

The user can access this information through some query routines. To keep in line with other routines in PTR, the query routines

• will have PTR_ as the common prefix
• will have the same get_* syntax like the tick-collecting routines
• will be sub-routines instead of functions
• will be all lowercase for C binding (except for the prefix) and all uppercase for Fortran binding
• will use DOUBLE PRECISION (FORTRAN) and double (C) for the timer parameters
• will have results returned via arguments passed by reference
• will report the status or any error condition via another argument passed by reference
• will return PTR_OK (see proposal PTR_OK section below) for successful completion
• will return PTR_NOT_AVAILABLE if the queried values are not available
• will return PTR_OTHER_ERROR for any other error condition

Synopsis:

        void PTR_get_wall_tick(double *val, int *status);
        void PTR_get_usr_tick(double *val, int *status);
        void PTR_get_sys_tick(double *val, int *status);
 
        void PTR_get_wall_resolution(double *val, int *status);
        void PTR_get_usr_resolution(double *val, int *status);
        void PTR_get_sys_resolution(double *val, int *status);

        void PTR_get_wall_rollover(double *val, int *status);
        void PTR_get_usr_rollover(double *val, int *status);
        void PTR_get_sys_rollover(double *val, int *status);

        void PTR_get_wall_overhead(double *val, int *status);
        void PTR_get_usr_overhead(double *val, int *status);
        void PTR_get_sys_overhead(double *val, int *status);

The FORTRAN binding corresponding to the last one above is as follows:

          DOUBLE PRECISION VAL
          INTEGER STATUS
          CALL PTR_GET_SYS_OVERHEAD(VAL, STATUS)

The reason for having these as subroutines and not as functions is the same reason why the tick-collecting routines were originally designed as subroutines as well. Here is a snippet from May 95 PTR working group report:

Response from Pancake:

There is one element that is not clear from the discussions, and which could make all the difference for a user:

• Can I query the value ahead-of-time (e.g., today) and store it in my own manifest constant for use later (e.g., next week)?

If so, I believe that the two problems,

>     However, two of the reasons for having the manifest constants
>     in the first place still remain valid:
>        - to provide enough information to the user about timers
>        - to provide efficient access to such information

would actually go away. That is, the user could choose whether to obtain the values on-the-fly, or retrieve them ahead of time and compile them as constants in his/her executable.

It would also let the user obtain the info ahead of time and use that data to help decide how many timer calls to insert, and at what points in execution, in order to avoid timer rollover (which was one of the reasons for having them available via the include file).

(2) Simplify calibration

Current situation:

There is no clear consensus on how to do calibration. With static manifest constants calibration must be done during the compilation or installation of the PTR library. This means that applications built on one system will not be portable to other binary compatible systems (that may be faster or slower).

Proposal:

Simplify calibration by maintaining one set of (runtime) timer characteristics (see above). These timer characteristics would be used by the timer characterization routines and the interval routines can use. The user could request finer grained calibration through. The user could request finer grained calibration through the init routines.

Rationale: While the above timer characterization routines hide the timer parameters behind query routines, they also make different calibration strategies possible. The user doesn't have to look at a different set of values after calibration as he/she did with manifest constants. The interval- calculating routines also don't have to handle two sets of timer values before and after calibration. The timer characterization functions transparently provide access to the most recent values of timer parameters.

In addition to the issue of insulating the user and interval-calculating routines from calibrations, there is the issue of when to calibrate. We can think of two different junctures to calibrate the timer parameters:

Compile-time/Install-time: This is done when the PTR library is being compiled on a system. The compilation setup can find out the most appropriate values for the timer parameters and place them in the source code before compilation. This might mean setting the initial value of a process-wide global variable. With this methodology, the timer parameter values are hard-coded in the library after installation. But this alone might be sufficient on certain platforms. Note that this calibration is not exposed to the user at all.

Runtime: This type of calibration is appropriate when one wants to capture the latest status of the system in its effect on the timer parameters. We propose that the runtime calibration capability be provided to the user via the init routines. The impact of calibrating at run-time is two-fold:

• the query routines will then return the new calibrated values
• the interval calculating routines will use the calibrated values.

The exact technique of calibration is left to the vendor. The vendor can choose to do nothing when the user requests calibration.

We have to specify what the user needs to provide for calibration. The common consensus seems to a time period for which the calibration has to run for.

(3) Simplify initialization interfaces

Current situation:

The signatures for the initialization routines are of the form:

            void PTR_init__timer(double* opt_ticksize,
                                        double init_level, 
                                        int *status);
    where:    
        opt_ticksize - if 0, then ticksize will be calculated
        init_level - amount of time to be spent calibrating
        status - int* where status code will be returned

Proposal:

With this in mind, the proposed synopsis for init routines is as follows:

       void PTR_init_wall_timer(double len, int *status);
       void PTR_init_usr_timer(double len, int *status);
       void PTR_init_sys_timer(double len, int *status);

If 'len' is 0, no calibration is done. But the timer parameters are set to what is most appropriate for the system without calibration. This might be making a system call to find out what the appropriate values are or might be setting a variable from a #defined constant. The vendor is free to do what is most appropriate for his/her implementation.

If 'len' is non-zero, and the vendor supports calibration, the timer parameters are calibrated. One should note that it is not within the PTR realm to decide what kinds of calibrations are possible. It is up to the vendor to document and support various kinds of calibration.

Any error codes or status codes are returned via the 'status' argument.

Rationale:

With the above proposals for timer characterization and calibration methodology, the specs for an init routine are quite clear:

• Init routine should set up correct values for timer parameters
• Use of init routine is 'required' to support run-time values for timer parameters
• Init routine should be able to calibrate the timer parameters as well
• Users should be able to specify the length of calibration time

(4)Add PTR_OK to PTR status values

Current situation:

The current PTR specs provide the following status values:

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

But it doesn't provide a status value for successful completion.

Proposal:

So the proposal is to add PTR_OK = 1 to the list of possible status values.

Response from Pancake:

This is almost a no-brainer, since the way we originally discussed the status codes (problems to be registered as neative status codes) was so that the traditional value, zero, could be used to indicate successful completion. I believe that our failure to include it was just an oversight. (If I'm wrong, someone +please+ correct me)

But I suggest that we add PTR_OK = 0 to conform to the common practice of using zero to represent successful completion.

---

For further information, contact kennino@cs.orst.edu.