Email Discussions of Pending Issues - Summer '96

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.
Replace these manifest constants with runtime (timer characterization) functions.
Manifest constants have been a source of heated discussions from the beginning and have given rise to several problems including the following: However, two of the reasons for having the manifest constants in the first place still remain valid: We can satisfy the above functional requirements by using run-time values to characterize the timers. This will also The user can access this information through some query routines. To keep in line with other routines in PTR, the query routines
        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:
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: 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).
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 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);
        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
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.

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

(4)Add PTR_OK to PTR status values

Current situation:
The current PTR specs provide the following status values:
        PTR_NOT_AVAILABLE = -1
        PTR_OTHER_ERROR = -4
But it doesn't provide a status value for successful completion.
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