Copyright © 1985 by Xerox Corporation. All rights reserved.

MBrown on November 29, 1982 2:04 pm

Cattell on March 14, 1983 2:08 pm

Willie-Sue on February 15, 1985 11:09:54 am PST

Widom, August 26, 1985 10:52:23 am PDT

Donahue, March 6, 1986 8:05:19 am PST

This is the interface to the Cedar database statistics gathering facility.

There are two kinds of "events": counter and timer.

Counter events are for logging the freqency with which a specific action or set of

actions is performed. If e is a counter event, then Inc[e] causes e's counter to be

incremented by 1. Inc[e] is very inexpensive to perform.

Timer events are for logging the time required for a specific action or set of

actions. If e is a timer event, then Starting[e] records the current time in a

variable associated with e. Then when Stopping[e] is performed at some later time,

it notes the difference between the current time and the time recorded by the

previous Starting[e]. At a minimum, the average value of this time interval is

maintained; a more elaborate implementation may also be supplied (max value,

standard deviation, histogram, ...). Starting[e] and Stopping[e] involve one

procedure call each and hence are more expensive than Inc[e] (but note that events

are statically typed so only one set of operations applies to an event in any case).

When two calls to Starting[e] occur in succession with no intervening Stopping[e],

the first Starting[e] is ignored; when two calls to Stopping[e] occur consecutively,

the last is ignored. Each of these situations counts as a "glitch", and the number

of glitches is reported for debugging purposes during Print, described below.

Glitches may occur due to a failure to call Stopping[e] during the UNWIND of a

procedure activation that called Starting[e]; a glitch is not a fatal error because

we consider it cumbersome to provide a catch for UNWIND simply to avoid glitches.

Any program using this package must initialize the stats implementation module by

calling DBStats.Initialize[] before calling Inc[e] or Starting[e]. The current

state of all active counters and timers is appended to the file "DBStats.log" by

DBStats.Print[]; this does not change the state of counters or timers, but resets

the count of glitches to 0. ERROR is raised if Print is called before Initialize.

Initialize should be called to reinitialize the stats module after printing if

independent statistics are desired.

Inc[e], Starting[e], and Stopping[e] are all INLINE procedures, and calls to them

with compile-time constant parameters produce no code when the procedure bodies

below are made empty. Hence calls to these procedures may be imbedded freely in a

system for testing, and then this defs module can be stubbed (all procs INLINE with

empty bodies) for the efficient "production" version.

Initialize: PROC[];

CounterEvent: TYPE = {

};

Inc: PROC[event: CounterEvent] =

TimerEvent: TYPE = {

};

FileTimerEvent: TYPE = TimerEvent [AlpineFileCreateTransaction .. AlpineFileSetSize];

Starting: PROC[event: TimerEvent] = INLINE { StartTimer[event] };

Stopping: PROC[event: TimerEvent] = INLINE { StopTimer[event] };

Aborting: PROC[event: TimerEvent] = INLINE { AbortTimer[event] };

Print: PROC[heading: Rope.ROPE ← NIL, out: IO.STREAM← NIL, verbose: BOOLEAN ← FALSE];

Private implementation details

CounterArray: PRIVATE ARRAY CounterEvent OF LONG CARDINAL;

StartTimer: PRIVATE PROC[event: TimerEvent];

StopTimer: PRIVATE PROC[event: TimerEvent];

AbortTimer: PRIVATE PROC[event: TimerEvent];