NSRunLoop Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSRunLoop.h
Related sample code

Overview

The NSRunLoop class declares the programmatic interface to objects that manage input sources. An NSRunLoop object processes input for sources such as mouse and keyboard events from the window system, NSPort objects, and NSConnection objects. An NSRunLoop object also processes NSTimer events.

Your application cannot either create or explicitly manage NSRunLoop objects. Each NSThread object, including the application’s main thread, has an NSRunLoop object automatically created for it as needed. If you need to access the current thread’s run loop, you do so with the class method currentRunLoop.

Note that from the perspective of NSRunloop, NSTimer objects are not "input"—they are a special type, and one of the things that means is that they do not cause the run loop to return when they fire.

Tasks

Accessing Run Loops and Modes

Managing Timers

Managing Ports

Running a Loop

Scheduling and Canceling Messages

Class Methods

currentRunLoop

Returns the NSRunLoop object for the current thread.

+ (NSRunLoop *)currentRunLoop
Return Value

The NSRunLoop object for the current thread.

Discussion

If a run loop does not yet exist for the thread, one is created and returned.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

mainRunLoop

Returns the run loop of the main thread.

+ (NSRunLoop *)mainRunLoop
Return Value

An object representing the main thread’s run loop.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

Instance Methods

acceptInputForMode:beforeDate:

Runs the loop once or until the specified date, accepting input only for the specified mode.

- (void)acceptInputForMode:(NSString *)mode beforeDate:(NSDate *)limitDate
Parameters
mode

The mode in which to run. You may specify custom modes or use one of the modes listed in “Run Loop Modes.”

limitDate

The date up until which to run.

Discussion

If no input sources or timers are attached to the run loop, this method exits immediately; otherwise, it runs the run loop once, returning as soon as one input source processes a message or the specifed time elapses.

Manually removing all known input sources and timers from the run loop is not a guarantee that the run loop will exit. OS X can install and remove additional input sources as needed to process requests targeted at the receiver’s thread. Those sources could therefore prevent the run loop from exiting.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

addPort:forMode:

Adds a port as an input source to the specified mode of the run loop.

- (void)addPort:(NSPort *)aPort forMode:(NSString *)mode
Parameters
aPort

The port to add to the receiver.

mode

The mode in which to add aPort. You may specify a custom mode or use one of the modes listed in “Run Loop Modes.”

Discussion

This method schedules the port with the receiver. You can add a port to multiple input modes. When the receiver is running in the specified mode, it dispatches messages destined for that port to the port’s designated handler routine.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

addTimer:forMode:

Registers a given timer with a given input mode.

- (void)addTimer:(NSTimer *)aTimer forMode:(NSString *)mode
Parameters
aTimer

The timer to register with the receiver.

mode

The mode in which to add aTimer. You may specify a custom mode or use one of the modes listed in “Run Loop Modes.”

Discussion

You can add a timer to multiple input modes. While running in the designated mode, the receiver causes the timer to fire on or after its scheduled fire date. Upon firing, the timer invokes its associated handler routine, which is a selector on a designated object.

The receiver retains aTimer. To remove a timer from all run loop modes on which it is installed, send an invalidate message to the timer.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

cancelPerformSelector:target:argument:

Cancels the sending of a previously scheduled message.

- (void)cancelPerformSelector:(SEL)aSelector target:(id)target argument:(id)anArgument
Parameters
aSelector

The previously-specified selector.

target

The previously-specified target.

anArgument

The previously-specified argument.

Discussion

You can use this method to cancel a message previously scheduled using the performSelector:target:argument:order:modes: method. The parameters identify the message you want to cancel and must match those originally specified when the selector was scheduled. This method removes the perform request from all modes of the run loop.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

cancelPerformSelectorsWithTarget:

Cancels all outstanding ordered performs scheduled with a given target.

- (void)cancelPerformSelectorsWithTarget:(id)target
Parameters
target

The previously-specified target.

Discussion

This method cancels the previously scheduled messages associated with the target, ignoring the selector and argument of the scheduled operation. This is in contrast to cancelPerformSelector:target:argument:, which requires you to match the selector and argument as well as the target. This method removes the perform requests for the object from all modes of the run loop.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

currentMode

Returns the receiver's current input mode.

- (NSString *)currentMode
Return Value

The receiver's current input mode. This method returns the current input mode only while the receiver is running; otherwise, it returns nil.

Discussion

The current mode is set by the methods that run the run loop, such as acceptInputForMode:beforeDate: and runMode:beforeDate:.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSRunLoop.h

getCFRunLoop

Returns the receiver's underlying CFRunLoop Reference object.

- (CFRunLoopRef)getCFRunLoop
Return Value

The receiver's underlying CFRunLoop Reference object.

Discussion

You can use the returned run loop to configure the current run loop using Core Foundation function calls. For example, you might use this function to set up a run loop observer.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

limitDateForMode:

Performs one pass through the run loop in the specified mode and returns the date at which the next timer is scheduled to fire.

- (NSDate *)limitDateForMode:(NSString *)mode
Parameters
mode

The run loop mode to search. You may specify custom modes or use one of the modes listed in “Run Loop Modes.”

Return Value

The date at which the next timer is scheduled to fire, or nil if there are no input sources for this mode.

Discussion

The run loop is entered with an immediate timeout, so the run loop does not block, waiting for input, if no input sources need processing.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

performSelector:target:argument:order:modes:

Schedules the sending of a message on the current run loop.

- (void)performSelector:(SEL)aSelector target:(id)target argument:(id)anArgument order:(NSUInteger)order modes:(NSArray *)modes
Parameters
aSelector

A selector that identifies the method to invoke. This method should not have a significant return value and should take a single argument of type id.

target

The object that defines the selector in aSelector.

anArgument

The argument to pass to the method when it is invoked. Pass nil if the method does not take an argument.

order

The priority for the message. If multiple messages are scheduled, the messages with a lower order value are sent before messages with a higher order value.

modes

An array of input modes for which the message may be sent. You may specify custom modes or use one of the modes listed in “Run Loop Modes.”

Discussion

This method sets up a timer to perform the aSelector message on the current thread’s run loop at the start of the next run loop iteration. The timer is configured to run in the modes specified by the modes parameter. When the timer fires, the thread attempts to dequeue the message from the run loop and perform the selector. It succeeds if the run loop is running and in one of the specified modes; otherwise, the timer waits until the run loop is in one of those modes.

This method returns before the aSelector message is sent. The receiver retains the target and anArgument objects until the timer for the selector fires, and then releases them as part of its cleanup.

Use this method if you want multiple messages to be sent after the current event has been processed and you want to make sure these messages are sent in a certain order.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

removePort:forMode:

Removes a port from the specified input mode of the run loop.

- (void)removePort:(NSPort *)aPort forMode:(NSString *)mode
Parameters
aPort

The port to remove from the receiver.

mode

The mode from which to remove aPort. You may specify a custom mode or use one of the modes listed in “Run Loop Modes.”

Discussion

If you added the port to multiple input modes, you must remove it from each mode separately.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

run

Puts the receiver into a permanent loop, during which time it processes data from all attached input sources.

- (void)run
Discussion

If no input sources or timers are attached to the run loop, this method exits immediately; otherwise, it runs the receiver in the NSDefaultRunLoopMode by repeatedly invoking runMode:beforeDate:. In other words, this method effectively begins an infinite loop that processes data from the run loop’s input sources and timers.

Manually removing all known input sources and timers from the run loop is not a guarantee that the run loop will exit. OS X can install and remove additional input sources as needed to process requests targeted at the receiver’s thread. Those sources could therefore prevent the run loop from exiting.

If you want the run loop to terminate, you shouldn't use this method. Instead, use one of the other run methods and also check other arbitrary conditions of your own, in a loop. A simple example would be:

BOOL shouldKeepRunning = YES;        // global
NSRunLoop *theRL = [NSRunLoop currentRunLoop];
while (shouldKeepRunning && [theRL runMode:NSDefaultRunLoopMode beforeDate:[NSDate distantFuture]]);

where shouldKeepRunning is set to NO somewhere else in the program.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSRunLoop.h

runMode:beforeDate:

Runs the loop once, blocking for input in the specified mode until a given date.

- (BOOL)runMode:(NSString *)mode beforeDate:(NSDate *)limitDate
Parameters
mode

The mode in which to run. You may specify custom modes or use one of the modes listed in “Run Loop Modes.”

limitDate

The date until which to block.

Return Value

YES if the run loop ran and processed an input source or if the specified timeout value was reached; otherwise, NO if the run loop could not be started.

Discussion

If no input sources or timers are attached to the run loop, this method exits immediately and returns NO; otherwise, it returns after either the first input source is processed or limitDate is reached. Manually removing all known input sources and timers from the run loop does not guarantee that the run loop will exit immediately. OS X may install and remove additional input sources as needed to process requests targeted at the receiver’s thread. Those sources could therefore prevent the run loop from exiting.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSRunLoop.h

runUntilDate:

Runs the loop until the specified date, during which time it processes data from all attached input sources.

- (void)runUntilDate:(NSDate *)limitDate
Parameters
limitDate

The date up until which to run.

Discussion

If no input sources or timers are attached to the run loop, this method exits immediately; otherwise, it runs the receiver in the NSDefaultRunLoopMode by repeatedly invoking runMode:beforeDate: until the specified expiration date.

Manually removing all known input sources and timers from the run loop is not a guarantee that the run loop will exit. OS X can install and remove additional input sources as needed to process requests targeted at the receiver’s thread. Those sources could therefore prevent the run loop from exiting.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSRunLoop.h

Constants

Run Loop Modes

NSRunLoop defines the following run loop mode.

extern NSString* const NSDefaultRunLoopMode;
extern NSString* const NSRunLoopCommonModes;
Constants
NSDefaultRunLoopMode

The mode to deal with input sources other than NSConnection objects.

This is the most commonly used run-loop mode.

Available in iOS 2.0 and later.

Declared in NSRunLoop.h.

NSRunLoopCommonModes

Objects added to a run loop using this value as the mode are monitored by all run loop modes that have been declared as a member of the set of “common" modes; see the description of CFRunLoopAddCommonMode for details.

Available in iOS 2.0 and later.

Declared in NSRunLoop.h.

Declared In
Foundation/NSRunLoop.h

Additional run loop modes are defined by NSConnection and NSApplication.

NSConnectionReplyMode
NSModalPanelRunLoopMode
NSEventTrackingRunLoopMode