NSTimer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSTimer.h
Companion guides
Related sample code

Overview

You use the NSTimer class to create timer objects or, more simply, timers. A timer waits until a certain time interval has elapsed and then fires, sending a specified message to a target object. For example, you could create an NSTimer object that sends a message to a window, telling it to update itself after a certain time interval.

Timers work in conjunction with run loops. To use a timer effectively, you should be aware of how run loops operate—see NSRunLoop and Threading Programming Guide. Note in particular that run loops maintain strong references to their timers, so you don’t have to maintain your own strong reference to a timer after you have added it to a run loop.

A timer is not a real-time mechanism; it fires only when one of the run loop modes to which the timer has been added is running and able to check if the timer’s firing time has passed. Because of the various input sources a typical run loop manages, the effective resolution of the time interval for a timer is limited to on the order of 50-100 milliseconds. If a timer’s firing time occurs during a long callout or while the run loop is in a mode that is not monitoring the timer, the timer does not fire until the next time the run loop checks the timer. Therefore, the actual time at which the timer fires potentially can be a significant period of time after the scheduled firing time. See also “Timer Tolerance.”

NSTimer is “toll-free bridged” with its Core Foundation counterpart, CFRunLoopTimerRef. See “Toll-Free Bridging” for more information on toll-free bridging.

Repeating Versus Non-Repeating Timers

You specify whether a timer is repeating or non-repeating at creation time. A non-repeating timer fires once and then invalidates itself automatically, thereby preventing the timer from firing again. By contrast, a repeating timer fires and then reschedules itself on the same run loop.

A repeating timer always schedules itself based on the scheduled firing time, as opposed to the actual firing time. For example, if a timer is scheduled to fire at a particular time and every 5 seconds after that, the scheduled firing time will always fall on the original 5 second time intervals, even if the actual firing time gets delayed. If the firing time is delayed so far that it passes one or more of the scheduled firing times, the timer is fired only once for that time period; the timer is then rescheduled, after firing, for the next scheduled firing time in the future.

Timer Tolerance

In iOS 7 and later and OS X v10.9 and later, you can specify a tolerance for a timer (setTolerance:). Allowing the system flexibility in when a timer fires improves the ability of the system to optimize for increased power savings and responsiveness. The timer may fire at any time between its scheduled fire date and the scheduled fire date plus the tolerance. The timer will not fire before the scheduled fire date. For repeating timers, the next fire date is calculated from the original fire date regardless of tolerance applied at individual fire times, to avoid drift. The default value is zero, which means no additional tolerance is applied. The system reserves the right to apply a small amount of tolerance to certain timers regardless of the value of the tolerance property.

As the user of the timer, you will have the best idea of what an appropriate tolerance for a timer may be. A general rule of thumb, though, is to set the tolerance to at least 10% of the interval, for a repeating timer. Even a small amount of tolerance will have a significant positive impact on the power usage of your application. The system may put a maximum value of the tolerance.

Scheduling Timers in Run Loops

A timer object can be registered in only one run loop at a time, although it can be added to multiple run loop modes within that run loop. There are three ways to create a timer:

Once scheduled on a run loop, the timer fires at the specified interval until it is invalidated. A non-repeating timer invalidates itself immediately after it fires. However, for a repeating timer, you must invalidate the timer object yourself by calling its invalidate method. Calling this method requests the removal of the timer from the current run loop; as a result, you should always call the invalidate method from the same thread on which the timer was installed. Invalidating the timer immediately disables it so that it no longer affects the run loop. The run loop then removes the timer (and the strong reference it had to the timer), either just before the invalidate method returns or at some later point. Once invalidated, timer objects cannot be reused.

Subclassing Notes

You should not attempt to subclass NSTimer.

Tasks

Creating a Timer

Firing a Timer

Stopping a Timer

Information About a Timer

Firing Tolerance

Class Methods

scheduledTimerWithTimeInterval:invocation:repeats:

Creates and returns a new NSTimer object and schedules it on the current run loop in the default mode.

+ (NSTimer *)scheduledTimerWithTimeInterval:(NSTimeInterval)seconds invocation:(NSInvocation *)invocation repeats:(BOOL)repeats
Parameters
seconds

The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

invocation

The invocation to use when the timer fires. The invocation object maintains a strong reference to its arguments until the timer is invalidated.

repeats

If YES, the timer will repeatedly reschedule itself until invalidated. If NO, the timer will be invalidated after it fires.

Return Value

A new NSTimer object, configured according to the specified parameters.

Discussion

After seconds seconds have elapsed, the timer fires, invoking invocation.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

scheduledTimerWithTimeInterval:target:selector:userInfo:repeats:

Creates and returns a new NSTimer object and schedules it on the current run loop in the default mode.

+ (NSTimer *)scheduledTimerWithTimeInterval:(NSTimeInterval)seconds target:(id)target selector:(SEL)aSelector userInfo:(id)userInfo repeats:(BOOL)repeats
Parameters
seconds

The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

target

The object to which to send the message specified by aSelector when the timer fires. The timer maintains a strong reference to target until it (the timer) is invalidated.

aSelector

The message to send to target when the timer fires.

The selector should have the following signature: timerFireMethod: (including a colon to indicate that the method takes an argument). The timer passes itself as the argument, thus the method would adopt the following pattern:

- (void)timerFireMethod:(NSTimer *)timer
userInfo

The user info for the timer. The timer maintains a strong reference to this object until it (the timer) is invalidated. This parameter may be nil.

repeats

If YES, the timer will repeatedly reschedule itself until invalidated. If NO, the timer will be invalidated after it fires.

Return Value

A new NSTimer object, configured according to the specified parameters.

Discussion

After seconds seconds have elapsed, the timer fires, sending the message aSelector to target.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

timerWithTimeInterval:invocation:repeats:

Creates and returns a new NSTimer object initialized with the specified invocation object.

+ (NSTimer *)timerWithTimeInterval:(NSTimeInterval)seconds invocation:(NSInvocation *)invocation repeats:(BOOL)repeats
Parameters
seconds

The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead

invocation

The invocation to use when the timer fires. The timer instructs the invocation object to maintain a strong reference to its arguments.

repeats

If YES, the timer will repeatedly reschedule itself until invalidated. If NO, the timer will be invalidated after it fires.

Return Value

A new NSTimer object, configured according to the specified parameters.

Discussion

You must add the new timer to a run loop, using addTimer:forMode:. Then, after seconds have elapsed, the timer fires, invoking invocation. (If the timer is configured to repeat, there is no need to subsequently re-add the timer to the run loop.)

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

timerWithTimeInterval:target:selector:userInfo:repeats:

Creates and returns a new NSTimer object initialized with the specified object and selector.

+ (NSTimer *)timerWithTimeInterval:(NSTimeInterval)seconds target:(id)target selector:(SEL)aSelector userInfo:(id)userInfo repeats:(BOOL)repeats
Parameters
seconds

The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

target

The object to which to send the message specified by aSelector when the timer fires. The timer maintains a strong reference to this object until it (the timer) is invalidated.

aSelector

The message to send to target when the timer fires.

The selector should have the following signature: timerFireMethod: (including a colon to indicate that the method takes an argument). The timer passes itself as the argument, thus the method would adopt the following pattern:

- (void)timerFireMethod:(NSTimer *)timer
userInfo

Custom user info for the timer.

The timer maintains a strong reference to this object until it (the timer) is invalidated. This parameter may be nil.

repeats

If YES, the timer will repeatedly reschedule itself until invalidated. If NO, the timer will be invalidated after it fires.

Return Value

A new NSTimer object, configured according to the specified parameters.

Discussion

You must add the new timer to a run loop, using addTimer:forMode:. Then, after seconds seconds have elapsed, the timer fires, sending the message aSelector to target. (If the timer is configured to repeat, there is no need to subsequently re-add the timer to the run loop.)

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

Instance Methods

fire

Causes the receiver’s message to be sent to its target.

- (void)fire
Discussion

You can use this method to fire a repeating timer without interrupting its regular firing schedule. If the timer is non-repeating, it is automatically invalidated after firing, even if its scheduled fire date has not arrived.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

fireDate

Returns the date at which the receiver will fire.

- (NSDate *)fireDate
Return Value

The date at which the receiver will fire. If the timer is no longer valid, this method returns the last date at which the timer fired.

Discussion

Use the isValid method to verify that the timer is valid.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

initWithFireDate:interval:target:selector:userInfo:repeats:

Initializes a new NSTimer object using the specified object and selector.

- (id)initWithFireDate:(NSDate *)date interval:(NSTimeInterval)seconds target:(id)target selector:(SEL)aSelector userInfo:(id)userInfo repeats:(BOOL)repeats
Parameters
date

The time at which the timer should first fire.

seconds

For a repeating timer, this parameter contains the number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

target

The object to which to send the message specified by aSelector when the timer fires. The timer maintains a strong reference to this object until it (the timer) is invalidated.

aSelector

The message to send to target when the timer fires.

The selector should have the following signature: timerFireMethod: (including a colon to indicate that the method takes an argument). The timer passes itself as the argument, thus the method would adopt the following pattern:

- (void)timerFireMethod:(NSTimer *)timer
userInfo

Custom user info for the timer. The timer maintains a strong reference to this object until it (the timer) is invalidated. This parameter may be nil.

repeats

If YES, the timer will repeatedly reschedule itself until invalidated. If NO, the timer will be invalidated after it fires.

Return Value

The receiver, initialized such that, when added to a run loop, it will fire at date and then, if repeats is YES, every seconds after that.

Discussion

You must add the new timer to a run loop, using addTimer:forMode:. Upon firing, the timer sends the message aSelector to target. (If the timer is configured to repeat, there is no need to subsequently re-add the timer to the run loop.)

Availability
  • Available in OS X v10.2 and later.
Declared In
NSTimer.h

invalidate

Stops the receiver from ever firing again and requests its removal from its run loop.

- (void)invalidate
Discussion

This method is the only way to remove a timer from an NSRunLoop object. The NSRunLoop object removes its strong reference to the timer, either just before the invalidate method returns or at some later point.

If it was configured with target and user info objects, the receiver removes its strong references to those objects as well.

Special Considerations

You must send this message from the thread on which the timer was installed. If you send this message from another thread, the input source associated with the timer may not be removed from its run loop, which could prevent the thread from exiting properly.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTimer.h

isValid

Returns a Boolean value that indicates whether the receiver is currently valid.

- (BOOL)isValid
Return Value

YES if the receiver is still capable of firing or NO if the timer has been invalidated and is no longer capable of firing.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

setFireDate:

Resets the firing time of the receiver to the specified date.

- (void)setFireDate:(NSDate *)date
Parameters
date

The new date at which to fire the receiver. If the new date is in the past, this method sets the fire time to the current time.

Discussion

You typically use this method to adjust the firing time of a repeating timer. Although resetting a timer’s next firing time is a relatively expensive operation, it may be more efficient in some situations. For example, you could use it in situations where you want to repeat an action multiple times in the future, but at irregular time intervals. Adjusting the firing time of a single timer would likely incur less expense than creating multiple timer objects, scheduling each one on a run loop, and then destroying them.

You should not call this method on a timer that has been invalidated, which includes non-repeating timers that have already fired. You could potentially call this method on a non-repeating timer that had not yet fired, although you should always do so from the thread to which the timer is attached to avoid potential race conditions.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
NSTimer.h

setTolerance:

Sets the amount of time after the scheduled fire date that the timer may fire to the given interval.

- (void)setTolerance:(NSTimeInterval)tolerance
Parameters
tolerance

The amount of time after the scheduled firing time that the timer may fire.

Discussion

The default value is zero, which means no additional tolerance is applied.

Setting a tolerance for a timer allows it to fire later than the scheduled fire date. Allowing the system flexibility in when a timer fires increases the ability of the system to optimize for increased power savings and responsiveness.

The timer may fire at any time between its scheduled fire date and the scheduled fire date plus the tolerance. The timer will not fire before the scheduled fire date. For repeating timers, the next fire date is calculated from the original fire date regardless of tolerance applied at individual fire times, to avoid drift. The system reserves the right to apply a small amount of tolerance to certain timers regardless of the value of this property.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSTimer.h

timeInterval

Returns the receiver’s time interval.

- (NSTimeInterval)timeInterval
Return Value

The receiver’s time interval. If the receiver is a non-repeating timer, returns 0 (even if a time interval was set).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h

tolerance

Returns the amount of time after the scheduled fire date that the timer may fire.

- (NSTimeInterval)tolerance
Return Value

The amount of time after the scheduled firing time that the timer may fire.

Discussion

The default value is zero, which means no additional tolerance is applied. For details, see setTolerance:.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSTimer.h

userInfo

Returns the receiver's userInfo object.

- (id)userInfo
Return Value

The receiver's userInfo object.

Discussion

Do not invoke this method after the timer is invalidated. Use isValid to test whether the timer is valid.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTimer.h