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:
Several timing-related routines are available on the Macintosh, and each is useful in
certain situations. In general, you should:
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
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.*
THE UPTIME ROUTINE
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
inDesigning 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.
POLLING FROM THE EVENT LOOP
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.
______________________________
APPLICATION COMPATIBILITY
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.
______________________________
USING THE EXTENDED TIME MANAGER
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).
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.
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.