Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!usc!samsung!munnari.oz.au!uhccux!waikato!ldo
From: ldo@waikato.ac.nz (Lawrence D'Oliveiro, Waikato University)
Newsgroups: comp.sys.mac.programmer
Subject: Extended Time Manager in System 6.0.7
Message-ID: <2252.273af53c@waikato.ac.nz>
Date: 9 Nov 90 05:28:11 GMT
Organization: University of Waikato, Hamilton, New Zealand
Lines: 77

I don't recall seeing this mentioned anywhere in the 6.0.7 release notes,
but there is another System 7.0 goody that has been included in
System 6.0.7: the Extended Time Manager. This allows you to queue
periodic wakeups at very accurate intervals, with zero drift.

Here's a brief summary of how to use the new facilities.

There is a new extended TMTask record, as follows (note the two
extra fields on the end):

	Type
	    TMTask = { extended Time Manager task }
		Record
		    qLink : QElemPtr;	{ link to next queue element }
		    qType : Integer;	{ Time Manager uses this for indicating its version }
		    tmAddr : ProcPtr;	{ pointer to task, if any }
		    tmCount : LongInt;	{ unused time, +ve => ms, -ve => us }
		    tmWakeUp : LongInt;	{ time of last wakeup }
		    tmReserved : LongInt { future use }
		End {Record};
	    TMTaskPtr = ^TMTask;

And one new trap, InsXTime, which you call instead of InsTime,
to insert a TMTask into the queue:

	Procedure InsXTime
	  (
	    TheTask : TMTaskPtr
	  );

	    Inline
		$205F,		{ move.l (sp)+, a0 }
		$A458;		{ _InsXTime }

Once you've queued the TMTask with InsXTime, you use the same old
PrimeTime and RmvTime traps to start and remove the timer. The
only difference is that you must set the tmWakeUp field to zero
before the first call to PrimeTime; the Time Manager sets this to
an internal representation of the moment when the timer actually
goes off (though it's not clear whether this happens on the PrimeTime
call, or when the timer goes off), and on the next call to PrimeTime,
it measures the interval you specify from that moment, rather than
from the time of the call.

The end result is that you can do some processing when the timer
goes off, and then requeue the timer, without having to worry
about the time you took to do the processing causing any drift.

For those who were unaware of it, System 6.0.3 introduced a "revised"
Time Manager, which supports microsecond as well as millisecond
timings. You just specify a negative value for the "count" argument
to PrimeTime, and that's taken to be microseconds. The documentation
claims a maximum resolution of 20 microseconds.

If you're wondering how I found out about the new Time Manager,
I was mucking about with the Gestalt call, trying out all the
selectors, and was surprised to find the "tmgr" (Time Manager version)
selector returning a value of 3 instead of 2. I typed in the
"TimeMgrInfo" routine out of an interim Inside Mac Vol VI
I had--this routine makes calls to the Time Manager to determine
its version and what maximum interval it supports--and sure enough,
it reported the same result!

It also reported a maximum timing interval of 87724005 milliseconds--
I'm not sure if this number depends on your exact machine, system
version or what. Interesting.

Actually, I'm assuming that the Extended Time Manager has only
appeared with 6.0.6/6.0.7. For all I know, it was in 6.0.5.
Or 6.0.4...

Lawrence D'Oliveiro                       fone: +64-71-562-889
Computer Services Dept                     fax: +64-71-384-066
University of Waikato            electric mail: ldo@waikato.ac.nz
Hamilton, New Zealand    37^ 47' 26" S, 175^ 19' 7" E, GMT+13:00
"How did you know they were sergeants' quarters?"
"There were ten huts."