June 96 - Timing On The Macintosh
Timing
on the Macintosh
MARTIN MINOW
The
Macintosh offers a rich and flexible set of timing operations that allow you to
measure elapsed time, record the time an event occurs, and schedule actions for
future times. This article pulls together all the available timing options,
including the extended Time Manager and Microseconds routine added with System
7 and new routines that are available with the PCI-based Macintosh and Mac OS 8.
You've probably heard the expression, "Time is nature's way of keeping
everything from happening at once." Well, keeping things from happening at the
same time is especially important on computers, and they're particularly good
at keeping close track of time -- both "clock" time and relative time. This
article shows you how to take advantage of the timing options provided on the
Macintosh, including new routines that are available on the PCI-based Macintosh
and will also work under Mac OS 8.
There are three common situations in which applications need to keep track of
time:
- measuring elapsed time -- for example, for performance analysis or to see
how long it takes the user or some other external entity to perform an action
- recording an event -- for example, to time-stamp a record in a database
or to inform the user when an action occurs
- scheduling an event -- for example, to start or complete a
time-dependent task
Several timing-related routines are available on the
Macintosh, and each is useful in certain situations. In general, you should:
- Use GetDateTime (or GetTime) if you need to maintain information across
system restarts or need to relate an event to the calendar.
- Use TickCount if you need only a relatively crude measure of time or
need to run under System 6.
- Use the Time Manager's Microseconds routine or Time Manager tasks if
you need improved precision or some attention to drift-free timing. Because the
Time Manager is part of all versions of System 7, it provides the best service
to most clients.
- Use UpTime if you want the highest-precision timing available and run
only on PCI-based Macintosh systems or under Mac OS 8.
This article
presents the basics of some standard approaches to the three types of timing,
along with code examples using many of the timing tools at your disposal.
There's also a discussion of factors that can affect the precision of your
timing operations. A simple example of using Microseconds is included on
thisissue's CD.
The Macintosh provides several functions that can be used to measure elapsed
time. Your choice of routine depends on the degree of precision you require and
the system software you're running under.
The GetDateTime function returns the current clock time as the number of
seconds since January 1, 1904, and the GetTime function returns the clock time
in year, month, day, hour, minute, and second format (in a date-time record).
With their one-second resolution, however, these functions aren't well suited
to measuring elapsed code performance or the duration of user actions.
January 1, 1904, was chosen as the base for the Macintosh clock because it was
the first leap year of the twentieth century. 1900 wasn't a leap year because
leap years are skipped every 100 years for three centuries. On the fourth
century, which will be the year 2000, the leap year isn't skipped. This means
that by starting with 1904, Macintosh system programmers could save a half
dozen instructions in their leap-year checking code, which they thought was way
cool.*
One of the functions available for finer timing resolution is TickCount, which
returns the time elapsed since the system last started up in units of about
1/60 second. Until System 7, this was the only reasonable way to measure
sub-second intervals. With System 7, the Microseconds routine became available.
(Using the extended Time Manager is another possible method on System 7, but
it's more complicated and so isn't commonly used for that purpose.)
Furthermore, the PCI-based Macintosh (and Mac OS 8) provide UpTime, a
replacement for Microseconds.
The Microseconds routine returns the number of microseconds that have elapsed
since system startup as an unsigned 64-bit integer and offers a convenient way
of timing events and operations. Theoretically, it can resolve intervals of
about 20 microseconds, although in practice it can't time intervals that small
(for reasons given later, in the section on timing accuracy).
The value returned by Microseconds has the UnsignedWide structure, shown in
Listing 1. A signed wide structure is used for the result of subtracting two
Microseconds values to calculate elapsed time. UnsignedWide is defined in
Types.h of the universal headers, but is also shown in Listing 1 for
convenience.
Listing 1. Microseconds structures
struct UnsignedWide {
unsigned long hi;
unsigned long lo;
};
typedef struct UnsignedWide UnsignedWide;
struct wide {
signed long hi;
unsigned long lo;
};
typedef struct wide wide;
/*
* The sample code defines a SignedWide structure for consistency.
*/
typedef wide SignedWide;
To
time a routine, your application would do the following:
UnsignedWide startTime;
UnsignedWide endTime;
Microseconds(&startTime);
DoMyOperation();
Microseconds(&endTime);
Subtracting
startTime from endTime will yield the elapsed time. However, the 64-bit
Microseconds values are rather unwieldy to deal with. The simplest solution is
to convert them to double-precision floating-point numbers.
MicrosecondToDouble, shown in Listing 2, converts a Microseconds value to
double-precision floating point. Using double precision will retain accuracy
for all practical purposes. You can also use integer subtraction to get the
difference between the two times and convert the result to floating point (or
whatever you need) afterward. MicrosecondDelta, also in Listing 2, computes the
difference between two Microseconds result values, returning a signed 64-bit
integer to retain precision.
Listing 2. Microseconds routine support functions
#define kTwoPower32 (4294967296.0) /* 2^32 */
double MicrosecondToDouble(register const UnsignedWide *epochPtr)
{
register double result;
result = (((double) epochPtr->hi) * kTwoPower32) + epochPtr->lo;
return (result);
}
void MicrosecondDelta(register const UnsignedWide *startPtr,
register const UnsignedWide *endPtr,
register SignedWide *resultPtr)
{
if (endPtr->lo >= startPtr->lo)
resultPtr->hi = endPtr->hi - startPtr->hi;
else
resultPtr->hi = (endPtr->hi - 1) - startPtr->hi;
resultPtr->lo = endPtr->lo - startPtr->lo;
}
If you prefer using only integer arithmetic, the sample code on this issue's CD
includes a very simple -- and very inefficient -- 64-bit integer library with
add, subtract, multiply, and divide functions that can be used to calculate
time values. For a more complete 64-bit integer math library, see the article
"64-Bit Integer Math on 680x0 Machines" in develop Issue 26.*
PCI-based Macintosh systems and the Mac OS 8 operating system provide a new
routine, UpTime, that returns the value of the PowerPC internal clock. The
value that's returned has the data type AbsoluteTime and cannot be interpreted
directly by applications, because the units are system dependent and not
defined by the API. A library is provided to convert values of type
AbsoluteTime into formats whose units are known. This approach allows the
system to maximize precision and performance.
The time values returned by UpTime start at 0 at system startup and increase
monotonically for as long as it's running. To time a routine with UpTime, your
application might do the following:
AbsoluteTime startTime;
AbsoluteTime endTime;
AbsoluteTime elapsedTime;
Nanoseconds elapsedNanoseconds;
/* This is an UnsignedWide integer */
startTime = UpTime();
DoMyOperation();
endTime = UpTime();
elapsedTime = SubAbsoluteFromAbsolute(endTime, startTime);
elapsedNanoseconds = AbsoluteToNanoseconds(elapsedTime);
These
functions and others used to process AbsoluteTime values are described in
Designing PCI Cards and Drivers for Power Macintosh Computers.
If you need to record when an event occurred (for example, when a record was
added to a database), you can use the value returned by GetDateTime or GetTime.
In most situations, GetDateTime is easier to deal with, being more compact and
saving you from converting days, months, years, and so on into seconds for
computations.
Keep in mind that GetDateTime returns the local clock time, which means that
you can't always use its value to determine which of two records is earlier, as
they could have been created in different time zones or under different
daylight saving time rules. If being able to compare times across time zones is
important, your application should call the ReadLocation routine and store its
MachineLocation result at the time you record the event so that the application
can compute a location-independent value by converting the local time to GMT
(Greenwich Mean Time).
Unfortunately, the local time value returned by GetDateTime isn't coordinated
with the more precise values returned by Microseconds and UpTime. This makes it
difficult to record local times with fractional second resolution. Listing 3
shows one way to work around this problem. It's adapted from the
LogConvertTimestamp function in my PCI device driver sample library, which was
first published in develop Issue 22 ("Creating PCI Device Drivers"). Listing 3
also illustrates my simple 64-bit support library.
Listing 3. Time of day with fractional second resolution
void LogConvertTimestamp(
AbsoluteTime eventTime, /* Value to convert */
DateTimeRec *eventDateTime, /* Result goes here */
UInt32 *residualNanoseconds /* Fractional second */
)
{
Nanoseconds eventNanoseconds;
UnsignedWide eventSeconds, temp;
static const UnsignedWide kTenE9 = { 0, 1000000000L };
static UInt32 gUpTimeNumerator;
static UnsignedWide gUpTimeDenominator;
static Nanoseconds gNanosecondsAtStart = { 0, 0 };
/*
* If this is the first call, compute the offset between
* GetDateTime and UpTime.
*/
if (gNanosecondsAtStart.lo == 0 && gNanosecondsAtStart.hi == 0) {
UnsignedWide secondsAtStart;
AbsoluteTime absoluteTimeAtStart;
Nanoseconds upTimeAtStart, nanosecondsAtStart;
secondsAtStart.hi = 0;
GetDateTime(&secondsAtStart.lo);
upTimeAtStart = AbsoluteToNanoseconds(UpTime());
Multiply64(&secondsAtStart, kTenE9.lo, &nanosecondsAtStart);
Subtract64(&nanosecondsAtStart, &upTimeAtStart,
&gNanosecondsAtStart);
}
/*
* Convert the event time (UpTime value) to nanoseconds and add
* the local time epoch.
*/
eventNanoseconds = AbsoluteToNanoseconds(eventTime);
Add64(&gNanosecondsAtStart, &eventNanoseconds, &eventNanoseconds);
/*
* eventSeconds = eventNanoseconds /= 10e9;
* residualNanoseconds = eventNanoseconds % 10e9;
* Finally, compute the local time (seconds) and fraction.
*/
Divide64(&eventNanoseconds, &kTenE9, &eventSeconds);
*residualNanoseconds = eventNanoseconds.lo;
SecondsToDate(eventSeconds.lo, eventDateTime);
}
Actions can be scheduled at a specific time -- such as 3 P.M. -- or at a
relative time -- like "15 minutes from now." Here we'll look at how an
application can schedule an action for a specific time by polling from its
event loop and how to use the extended Time Manager to initiate an action after
a specific amount of time passes.
The simplest way for an application to schedule an action for a specific time
is to call GetDateTime every so often from the event loop and compare the
returned value with the time set for the scheduled event. (If all your
application is doing is polling for the right time to arrive, be nice and set
the WaitNextEvent sleep time to something long -- 15 seconds, perhaps.) When
the set time matches (or is earlier than) the returned value, the event occurs.
Of course, you can use this solution only if your program is an application
(normal or faceless-background). Code resources should use an extended Time
Manager task with a completion routine instead (as described in the next
section).
The event-loop approach works best when you want to schedule an action for a
specific time because the specified time will be observed even if the user
changes the system's date or time. (Note that under this approach, an event
that just occurred could occur again if the user changes the time backwards.)
However, if it's important that the action happen at some relative amount of
time in the future, you're better off polling with TickCount, Microseconds, or
UpTime or using an extended Time Manager task with a completion routine.
Macintosh applications need to check whether particular operating system
functions are available before using them. For example (as you'll see later in
Listing 5), the Gestalt function can be used to check for the presence of the
extended Time Manager and the Process Manager. This technique lets your
application configure itself to your customer's exact hardware and system.
If you want to add UpTime support to an application that must also run on
Macintosh systems that lack this function, you'll have to use a different
approach, because your PowerPC application uses the Code Fragment Manager to
link to the shared library that provides this service. If the shared library is
not present on the customer system, your application will not launch (and the
user will be quite perplexed). The simplest way to work around this problem is
to use your development environment's "weak link" or "soft import" capability.
By weak-linking these functions, your application will start even if the
necessary shared library isn't present. This technique is described in detail
in Inside Macintosh: PowerPC System Software, page 1-25.
The extended Time Manager was introduced in System 7 as a way to schedule
accurate periodic actions. Precise timing and real-time synchronization was
becoming more important with increasing use of sound and multimedia. In
addition, the extended Time Manager is the preferred way to schedule an action
for a code resource. Scheduling an action with the extended Time Manager is
suitable for waits of moderate duration (up to a day or so).
The following example uses the extended Time Manager to awaken a process 30
seconds after the timer is started. As shown in Listing 4, the first step is to
define an extended Time Manager task record that includes the timer task, the
process serial number of the process to awaken when the timer expires, and (on
680x0 systems) a pointer to the application's globals. (Throughout this example
we assume an application context, so this value is A5; for THINK and Metrowerks
nonapplication code, it should be A4 instead.) Listing 4 also defines the
interface for the Time Manager completion routine -- notice that it varies for
680x0 and PowerPC compilations.
Listing 4. Extended Time Manager definitions
#include <Types.h>
#include <Timer.h>
#include <OSUtils.h>
#include <GestaltEqu.h>
#include <Processes.h>
/* Define an extended task record. */
struct ExtendedTimerRec {
TMTask tmTask;
ProcessSerialNumber taskPSN;
#if GENERATINGPOWERPC
/* Nothing needed for PowerPC */
#else
long applicationA5;
#endif
};
typedef struct ExtendedTimerRec ExtendedTimerRec, *ExtendedTimerPtr;
/* Define the interface for a completion function. */
#if GENERATINGPOWERPC
pascal void TimerCallbackProc(TMTaskPtr tmTaskPtr);
#else /* 680x0 */
pascal void TimerCallbackProc(void);
/*
* This inline function returns the extended Time Manager task
* pointer, which is passed to the completion routine in register A1.
*/
pascal TMTaskPtr GetTMTaskPtr(void) = 0x2E89;
#endif
Before
you can use your extended task record, you need to be sure the extended Time
Manager and Process Manager are present on the system. Listing 5 shows code
that checks for their presence. If they're present, the code initializes the
extended task record (gExtendedTimerRec), installs the task in the extended
Time Manager's event queue, and starts the timer.
Listing 5. Starting the timer
long gestaltResponse;
if (Gestalt(gestaltTimeMgrVersion, &gestaltResponse) != noErr
|| (gestaltResponse < gestaltExtendedTimeMgr))
goto failure; /* The extended Time Manager is not present. */
if (Gestalt(gestaltOSAttr, &gestaltResponse) != noErr
|| (gestaltResponse & (1L << gestaltLaunchControl)) == 0)
goto failure; /* The Process Manager is not present. */
/*
* Configure the global structure that stores the timing
* information.
*/
gExtendedTimerRec.tmTask.qLink = NULL;
gExtendedTimerRec.tmTask.qType = 0;
gExtendedTimerRec.tmTask.tmAddr = NewTimerProc(TimerCallbackProc);
gExtendedTimerRec.tmTask.tmCount = 0;
gExtendedTimerRec.tmTask.tmWakeup = 0;
gExtendedTimerRec.tmTask.tmReserved = 0;
#if GENERATINGPOWERPC
/* Nothing needed for PowerPC. */
#else
gExtendedTimerRec.applicationA5 = SetCurrentA5();
#endif
GetCurrentProcess(&gExtendedTimerRec.taskPSN);
InsXTime((QElemPtr) &gExtendedTimerRec.tmTask);
/*
* Start the timer -- 30-second stall.
*/
PrimeTime((QElemPtr) &gExtendedTimerRec.tmTask, 30000L);
You
also need to define the extended Time Manager completion routine that's called
when the timer expires (see Listing 6).
Listing 6. Extended Time Manager completion routine
/*
* Define an extended Time Manager completion routine that awakens
* the specified application.
*/
#if GENERATINGPOWERPC
pascal void TimerCallbackProc(TMTaskPtr tmTaskPtr)
{
#else
pascal void TimerCallbackProc(void)
{
TMTaskPtr tmTaskPtr;
long oldA5;
tmTaskPtr = GetTMTaskPtr();
oldA5 = SetA5(((ExtendedTimerPtr) tmTaskPtr)->applicationA5);
#endif
gTimerFired = TRUE;
WakeUpProcess(&((ExtendedTimerPtr) tmTaskPtr)->taskPSN);
#if GENERATINGPOWERPC
/* Nothing needed at completion routine exit. */
#else
SetA5(oldA5);
#endif
}
The
completion routine is a one-shot timer that awakens the process and exits. You
can easily extend this to perform a periodic wake-up action. Again, note the
use of A5 (use A4 for nonapplication code written in THINK or Metrowerks).
TIMING ACCURACY, PRECISION, AND OVERHEAD
If you're measuring performance, remember that you can't trust a single
measurement, as it can be affected by a number of system-related asynchronous
events that you can't always control. Instead, you should take a number of
samples and use a statistical package to understand the variation that may
affect the accuracy and precision of your timing measurement.
On current Macintosh systems, the Microseconds routine uses the hardware VIA
timer as a basis for its calculation. This decrements at a rate of 783360 Hz
and, consequently, limits resolution to about 1.28 microseconds. (Of course,
the mechanism and resolution may change on future systems.) Due to
implementation limitations, however, the Microseconds routine can't time
intervals shorter than about 20 microseconds. If you're using Microseconds to
time a very short interval (such as the execution time of a small code
segment), your analysis may need to adjust the measurements to take into
account the computational overhead of the Microseconds routine itself. This
varies from machine to machine -- and depends, in part, on the influence of
other systemwide processes. An informal measurement of one machine showed that
the following sequence could take as little as zero time up to several hundred
milliseconds:
Microseconds(&startTime);
Microseconds(&endTime);
The
reason for this dispersion is that the internal timer is updated as a result of
system interrupts, such as VIA timer and extended Time Manager task completion.
Also, other asynchronous operations on the Macintosh, such as mouse-movement
handlers, file sharing, I/O completion, virtual memory page faults, and network
operations, will interrupt applications (and, on Mac OS 8, preemptive
multitasking). Thus, if you're using Microseconds to time application program
execution, it should be part of a more extensive statistical data analysis,
since any single measurement may result in incorrect data. As a rule of thumb,
to minimize the overhead of calling the routine itself, the smallest
measurement interval should be on the order of one millisecond.
A similar warning needs to be given regarding the long-term accuracy of the
Microseconds routine: The crystal oscillator used to generate the underlying
time base varies slightly, depending primarily on the ambient temperature.
Here, too, you should measure the actual behavior of your system. Given a 0.01%
normal drift rate for the clock, a drift of 8 seconds per day is not uncommon
(0.01% equals 1 second in 10,000 or about 8 seconds per day). For long-term
accuracy, you may need to rely on an external time source, such as a network
time service as specified in Internet RFC 1305, or a radio receiver tuned to a
national standard, such as WWV or WWVL.
With all the processes competing on a Macintosh, it's possible, even likely,
that several wait loops will end at the same instant, particularly on the
boundaries of seconds or minutes. This can cause unpredictable delays. While
the occasional long delay is not a problem for most ordinary desktop tasks, it
can be devastating for systems that record or play live audio or QuickTime
video. The developer of such a system must be very careful to avoid regular
scheduling: all delay values (such as the sleep time passed to WaitNextEvent)
should be varied by a small random value to minimize the chance of several wait
loops ending at the same instant.
Whether you're trying to analyze the performance of your code, schedule a
reminder for later, measure how long it takes users to complete a task, or
remember exactly when they completed it, there's a straightforward method for
doing it on the Macintosh. So go on, hook your programs up to the ever-flowing
stream of time. No matter what you like to do with your time -- spend it or
kill it, assess its quality or lose track of it -- your code will be able to
keep pace.
- For information on measuring performance, see The Art of Computer Systems
Performance Analysis by Raj Jain (John Wiley & Sons, Inc., 1991).
- TickCount, an Event Manager function, is described in Inside Macintosh:
Toolbox Essentials (Addison-Wesley, 1992), Chapter 2, "Event Manager," page
2-112. Other time-measurement routines (including ReadLocation) are described
in Inside Macintosh: Operating System Utilities (Addison-Wesley, 1994), Chapter
4, "Date, Time, and Measurement Utilities."
- The extended Time Manager is described in Inside Macintosh: Processes
(Addison-Wesley, 1992), Chapter 3, "Time Manager."
- UpTime and other new routines are described in Designing PCI Cards and
Drivers for Power Macintosh Computers (Apple Computer, Inc., 1995).
- The soft import capability is described in Inside Macintosh: Power PC
System Software (Addison-Wesley, 1994), Chapter 1, "Introduction to PowerPC
System Software."
Thanks to our technical reviewers Mark Baumwell, Gene
Garbutt, C. K. Haun, Matt Mora, and Wayne Meretsky.
MARTIN MINOW (minow@apple.com, AppleLink MINOW) appreciates a colleague's
e-mail signature: "Objects in calendars are closer than they appear." Martin is
writing the SCSI plug-in for Mac OS 8.
