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.

MEASURING ELAPSED TIME

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 in Designing PCI Cards and Drivers for Power Macintosh Computers.

RECORDING EVENT OCCURRENCE

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);
}

SCHEDULING FUTURE ACTIONS

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).

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.

TIMING IS EVERYTHING

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.

---

FURTHER READING

• 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.