MachTimer Class Reference

Download

Mach timers

Overview

The MachTimer class is a simple Objective-C wrapper of Mach absolute time. It is a one-shot (non-reusable) object with which you can easily measure time in your code.

A Mach timer instance is gotten from one of the two class methods, it is started (if necessary), it is stopped, and the duration is made available. The Mach timer doesn't actually at any point establish a timer - or "run". It simply records the Mach absolute time at two points - the "start" point and the "stop" point. The difference is calculated, converted into a floating-point NSTimeInterval (and at the same time into seconds from whatever scale Mach might provide) and made available when the Mach timer is stopped.

It is also possible to acquire a new Mach timer whose start time is identical to another instance. This can be useful for 'lap timing'.

Methods by Task

Creating Mach timers

Starting and stopping Mach timers and getting the duration

Getting the current state of the Mach timer

Constants and data structures

Mach timer status

Class Methods

startedMachTimer

Returns a started Mach timer.

+ (MachTimer *)startedMachTimer

Return Value

An autoreleased Mach timer.

unstartedMachTimer

Returns a Mach timer.

+ (MachTimer *)unstartedMachTimer

Return Value

An autoreleased Mach timer.

Instance Methods

duration

Returns the duration in seconds.

- (NSTimeInterval)duration

Return Value

The time in seconds as a floating-point NSTimeInterval.

Discussion

Can only be run after the Mach timer has been started and then stopped.

isStarted

Returns whether the Mach timer has been started.

- (BOOL)isStarted

Return Value

YES if the Mach timer has been started, otherwise NO.

See also

isStopped

Returns whether the Mach timer has been stopped.

- (BOOL)isStopped

Return Value

YES if the Mach timer has been started, otherwise NO.

Discussion

This method does not return YES before the Mach timer has been started. If this method is YES, a duration can be fetched from the duration method.

See also

machTimerWithIdenticalStartTime

Returns a new Mach timer initialized as if it was started at self's start time.

- (MachTimer *)machTimerWithIdenticalStartTime

Return Value

An autoreleased Mach timer.

Discussion

The returned Mach timer will not yet have been stopped.

start

Starts a Mach timer.

- (id)start

Discussion

The current implementation of Mach timers don't actually run as such. This method captures the current Mach absolute time which it stores.

See also

status

Returns the Mach timer's current status.

- (MachTimerStatus)status

Return Value

A MachTimerStatus value describing the state of the Mach timer.

See also

stop

Stops a Mach timer.

- (id)stop

Discussion

After this method, it is safe to call duration.

See also

stopAndReturnDuration

Stops a Mach timer and returns the duration in seconds.

- (NSTimeInterval)stopAndReturnDuration

Return Value

The time in seconds as a floating-point NSTimeInterval.

Discussion

This method calls stop, but does not call duration.

See also

Constants

MachTimerStatus

An enumeration whose constants describes the state of a Mach timer.

MachTimerStatus {
    MachTimerNotStarted = 0,
    MachTimerStarted = 1,
    MachTimerStopped = 2
}

Constants

MachTimerNotStarted
The state of the Mach timer if it has been created but not started yet.
MachTimerStarted
The state of the Mach timer if it has been created and started but not stopped yet.
MachTimerStopped
The state of the Mach timer if it has been created, started and then stopped.

Discussion

The state dictates what you can call on the Mach timer, and how much information is available.