Time Manager interfaces.
- Introduced In: Mac OS 8.5
- Avaliable From: Universal Interfaces 3.4.1
- Copyright: � 1985-2001 by Apple Computer, Inc., all rights reserved
For bug reports, consult the following page on the World Wide Web:
http://developer.apple.com/bugreporter/
Install timer task.
Trap macro _InsTime
On entry A0:address of TMTask record
On exit D0:result code
InsTime adds the Time Manager task record specified by tmTaskPtr to the
Time Manager queue. Your application should fill in the tmAddr field of the
task record and should set the remaining fields to 0. The tmTaskPtr parameter
must point to an original Time Manager task record.
With the revised and extended Time Managers, you can set tmAddr to NIL if
you do not want a task to execute when the delay passed to PrimeTime
expires. Also, calling InsTime with the revised Time Manager causes the
high-order bit of the qType field to be reset to 0.
InsTime enqueues a data structure in preparation for a subsequent call to
PrimeTime , which starts the clock ticking on a timer-alarm triggered task.
After the alarm goes off, your task is still in the Time Manager queue, but it
is no longer primed.
Use the InsXTime procedure if you want to take advantage of the drift-free,
fixed-frequency timing services of the extended
Time Manager .
tmTaskPtr is the address of a 12-byte TMTask structure. You must set the
tmAddr field of this structure to point to the code you wish executed
when the alarm is triggered. Other fields are set automatically.
- Returns
none
- Note
Time Manager alarms have resolution of 1ms (1/1000th of
a second). You may enqueue any number of these "wakeup" requests. None
takes effect until you call PrimeTime and the specified interval elapses.
The code of the timer task is executed at interrupt time, so it must be
written with the following constraints:
•It must not call Memory Manager functions directly or indirectly .
You cannot call any Toolbox routine that may move or purge
memory.Note: it is OK to call PrimeTime to set up for another alarm.
•It must not depend on handles of unlocked memory blocks to be valid.
•It must preserve the values of all registers except A0-A3 and D0-D3.
•If it accesses application globals, it must be sure that the A5 register
is valid.
The latter requirement is important. At interrupt time, you cannot depend
- Copyright: THINK Reference © 1991-1992 Symantec Corporation
- Non-Carbon CFM: in InterfaceLib 7.1 and later
- Carbon Lib: in CarbonLib 1.0 and later
- Mac OS X: in version 10.0 and later
| void PrimeTime |
( |
QElemPtr |
tmTaskPtr, |
|
|
long |
count |
|
) |
| |
Set interval for timer and start it ticking.
Trap macro _PrimeTime
On entry A0:address of TMTask record
D0:specified delay time (long)
On exit D0:result code
PrimeTime starts the clock ticking on a timer-alarm triggered task
previously prepared by means of a call to InsTime .
If the count parameter is a positive value, it is interpreted in milliseconds. If
count is a negative value, it is interpreted in negated microseconds.
(Microsecond delays are allowable only in the revised and extended Time
Managers.) The task record specified by tmTaskPtr must already be inserted
into the queue (by a previous call to InsTime or InsXTime ) before your
application calls the PrimeTime procedure. The PrimeTime procedure
returns immediately, and the specified routine is executed after the specified
delay has elapsed. If you call PrimeTime with a time delay of 0, the
procedure runs as soon as interrupts are enabled.
In the revised and extended Time Managers, PrimeTime sets the high-order
bit of the qType field to 1. In addition, any value of the count parameter that
exceeds the maximum millisecond delay is reduced to the maximum. If you
pause an unexpired task (with RmvTime ) and then reinstall it (with
InsXTime ), you can continue the previous delay by calling PrimeTime
with the count parameter set to 0.
tmTaskPtr is the address of a 12-byte TMTask structure previously used in a
call to InsTime .
msCount specifies how long, in milliseconds, to wait before calling your
wakeup routine.
- Returns
none
- Note
PrimeTime may be called more than once for any previously
installed Time Manager task (see InsTime ). Secondary calls override
the previously set interval. Thus, you can use this as a "watchdog" timer to
be called before you start some event that is prone to getting locked into a
loop.
PrimeTime does not make any demands on the Memory Manager , so it
can be called from inside your alarm handling routine in order to set a new
interval for that routine.
See InsTime for an example of usage.
- Copyright: THINK Reference © 1991-1992 Symantec Corporation
- Non-Carbon CFM: in InterfaceLib 7.1 and later
- Carbon Lib: in CarbonLib 1.0 and later
- Mac OS X: in version 10.0 and later
Remove task from Time Manager queue.
Trap macro _RmvTime
On entry A0:address of TMTask record
On exit D0:result code
RmvTime removes a previously installed element from the
Time Manager queue. If the clock was ticking on that timer, it
is stopped and its alarm handling routine will not be called.
The RmvTime procedure removes the Time Manager task record specified
by tmTaskPtr from the Time Manager queue. In both the revised and extended
Time Managers, if the specified task record is active (that is, it has been
activated but the specified time has not yet elapsed), the tmCount field of the
task record returns the amount of time remaining. To provide the greatest
accuracy, the unused time is reported as negated microseconds if that value is
small enough to fit into the tmCount field (even if the delay was originally
specified in milliseconds); otherwise, the unused time is reported in positive
milliseconds. If the time has already expired, tmCount contains 0.
In the revised and extended Time Managers, PrimeTime sets the high-order
bit of the qType field to 0.
tmTaskPtr is the address of a 12-byte TMTask structure previously used in a
call to InsTime .
- Returns
none
- Copyright: THINK Reference © 1991-1992 Symantec Corporation
- Non-Carbon CFM: in InterfaceLib 7.1 and later
- Carbon Lib: in CarbonLib 1.0 and later
- Mac OS X: in version 10.0 and later
1.9.1