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)
- Manifest constants have been a source of heated discussions from
the beginning and have given rise to several problems including
However, two of the reasons for having the manifest constants
in the first place still remain valid:
- Manifest constants are not suited very well for calibration.
Since they are constants, they cannot be replaced by
- 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
- The nominal values are also meaningless for machines from
vendors who support different resolutions.
We can satisfy the above functional requirements by using
run-time values to characterize the timers. This will also
- to provide enough information to the user about timers
- to provide efficient access to such information
The user can access this information through some query routines.
To keep in line with other routines in PTR, the query routines
- 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
- 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
- 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
- will return PTR_NOT_AVAILABLE if the queried values are not
- will return PTR_OTHER_ERROR for any other error condition
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
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:
If so, I believe that the two problems,
- 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)?
> 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
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.
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:
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.
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
The exact technique of calibration is left to the vendor. The vendor
can choose to do nothing when the user requests calibration.
- the query routines will then return the new calibrated values
- the interval calculating routines will use the calibrated
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,
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
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
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
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:
- 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
- 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_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
For further information, contact