Class

Timer

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.

Overview

Timers work in conjunction with run loops. To use a timer effectively, you should be aware of how run loops operate—see RunLoop 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, CFRunLoopTimer. 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 macOS 10.9 and later, you can specify a tolerance for a timer (tolerance). 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.

After a repeating timer fires, it schedules the next firing for the nearest future date that is an integer multiple of the timer interval after the last scheduled fire date, within the specified tolerance. If the time taken to call out to perform a selector or invocation is longer than the specified interval, the timer will only schedule the next firing; that is, the timer will not attempt to compensate for any missed firings that would have occurred while calling out to the specified selector or invocation.

Subclassing Notes

You should not attempt to subclass NSTimer.

Symbols

Creating a Timer

class func scheduledTimer(timeInterval: TimeInterval, invocation: NSInvocation, repeats: Bool)

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

class func scheduledTimer(timeInterval: TimeInterval, target: Any, selector: Selector, userInfo: Any?, repeats: Bool)

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

init(timeInterval: TimeInterval, invocation: NSInvocation, repeats: Bool)

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

init(timeInterval: TimeInterval, target: Any, selector: Selector, userInfo: Any?, repeats: Bool)

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

init(fireAt: Date, interval: TimeInterval, target: Any, selector: Selector, userInfo: Any?, repeats: Bool)

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

Firing a Timer

func fire()

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

Stopping a Timer

func invalidate()

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

Information About a Timer

var isValid: Bool

A Boolean value that indicates whether the receiver is currently valid.

var fireDate: Date

The date at which the timer will fire.

var timeInterval: TimeInterval

The timer’s time interval.

var userInfo: Any?

The receiver's userInfo object.

Firing Tolerance

var tolerance: TimeInterval

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

Relationships

Inherits From

Conforms To