---

Time Manager Reference

Overview

The Time Manager allows applications and other software to schedule routines for execution at a later time. By suitably defining the routine that is to be executed later, you can use the Time Manager to accomplish a wide range of time-related activities. For example, because a routine can reschedule itself for later execution, the Time Manager allows your application to perform periodic or repeated actions. You can use the Time Manager to schedule routines for execution after a specified delay; set up tasks that run periodically; compute the time a routine takes to run; and coordinate and synchronize actions in the Macintosh computer.

The Time Manager provides a hardware-independent method of performing these time-related tasks. In general, you should use the Time Manager instead of timing loops, which can vary in duration because they depend on clock speed and interrupt-handling speed.

Carbon supports the Time Manager. However, the interface for callbacks will change because the current task record is accessible only from 68K code.

Functions by Task

Installing and Removing Tasks

• InstallTimeTask Deprecated in Mac OS X v10.4
• InstallXTimeTask Deprecated in Mac OS X v10.4
• RemoveTimeTask Deprecated in Mac OS X v10.4

Activating Tasks

• PrimeTimeTask Deprecated in Mac OS X v10.4

Measuring Time

• Microseconds

Working With Your Time Manager Callback Function

• NewTimerUPP
• InvokeTimerUPP
• DisposeTimerUPP

Obsolete Functions

• InsTime Deprecated in Mac OS X v10.4
• InsXTime Deprecated in Mac OS X v10.4
• PrimeTime Deprecated in Mac OS X v10.4
• RmvTime Deprecated in Mac OS X v10.4

Functions

DisposeTimerUPP

Disposes of the universal procedure pointer (UPP) to your Time Manager task callback function. (Deprecated. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

void DisposeTimerUPP (
   TimerUPP userUPP
);

Parameters

userUPP

A UPP to your callback function.

Discussion

See the callback TimerProcPtr for more information.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability

• Available in CarbonLib 1.0 and later.
• Available in Mac OS X 10.0 and later.

Declared In

Timer.h

InvokeTimerUPP

Invokes your Time Manager task callback function. (Deprecated. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

void InvokeTimerUPP (
   TMTaskPtr tmTaskPtr,
   TimerUPP userUPP
);

Parameters

tmTaskPtr

A pointer to a structure of type TMTask containing the information about the task.

userUPP

A UPP to your callback function.

Discussion

See the callback TimerProcPtr for more information.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability

• Available in CarbonLib 1.0 and later.
• Available in Mac OS X 10.0 and later.

Declared In

Timer.h

Microseconds

Determines the number of microseconds that have elapsed since system startup time.

void Microseconds (
   UnsignedWide *microTickCount
);

Parameters

microTickCount

The number of microseconds elapsed since system startup.

Availability

• Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later.
• Available in Mac OS X 10.0 and later.

Declared In

Timer.h

NewTimerUPP

Creates a new universal procedure pointer (UPP) to your Time Manager task callback. (Deprecated. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

TimerUPP NewTimerUPP (
   TimerProcPtr userRoutine
);

Parameters

userRoutine

A pointer to your Time Manager event callback function. For information on how to create a Time Manager event callback see TimerProcPtr

Return Value

A UPP to your callback function. See the description of the TimerUPP data type.

Discussion

See the callback TimerProcPtr for more information.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability

• Available in CarbonLib 1.0 and later.
• Available in Mac OS X 10.0 and later.

Declared In

Timer.h

Callbacks

TimerProcPtr

Defines a pointer to your application-defined Time Manager task that is executed after a specified delay.

typedef void (*TimerProcPtr) (
   TMTaskPtr tmTaskPtr
);

If you name your function MyTimerProc, you would declare it like this:

void MyTimerProc (
   TMTaskPtr tmTaskPtr
);

Parameters

tmTaskPtr

A pointer to a structure of type TMTask containing the information about the task.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Timer.h

Data Types

TimerUPP

Defines a data type for the TimerProcPtr callback function.

typedef TimerProcPtr TimerUPP;

Discussion

For more information, see the description of the TimerProcPtr callback function.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Timer.h

TMTask

Contains information for a Time Manager task.

struct TMTask {
   QElemPtr qLink;
   short qType;
   TimerUPP tmAddr;
   long tmCount;
   long tmWakeUp;
   long tmReserved;
};
typedef struct TMTask TMTask;
typedef TMTask * TMTaskPtr;

Fields

qLink

A pointer to the next element in the Time Manager queue. This field is used internally by the Time Manager.

qType

The type of queue. The Time Manager automatically sets this field to the appropriate value. The high-order bit of this field is a flag that indicates whether the task is active.

tmAddr

A pointer to the function that is to execute after the delay specified in a call to PrimeTime.

tmCount

Reserved in the original Time Manager. In the revised or extended Time Manager, the amount of time remaining until the task’s scheduled execution time. This field is valid only after you call RmvTime with a task that has not yet executed.

tmWakeUp

In the extended Time Manager, the time when the task specified in the tmAddr field was last executed. This field is used internally by the Time Manager. You should set it to 0 when you first install a task structure.

tmReserved

Reserved.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Timer.h

Constants

Active Task Constant

Defines a constant for an active task.

enum {
   kTMTaskActive = (1L << 15)
};

Constants

kTMTaskActive

The high bit of the qType field in the TMTask structure is set if the task is active.

Available in Mac OS X v10.0 and later.

Declared in Timer.h.

Result Codes

The most common result codes returned by Time Manager is noErr, which has a value of 0.

Gestalt Constants

You can check for version and feature availability information by using the Time Manager Version selectors defined in the Gestalt Manager. For more information see Inside Mac OS X: Gestalt Manager Reference.

---