Next Page > Hide TOC

NSRunLoop Class Reference

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.

In general, your application does not need to 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.

Warning:  The NSRunLoop class is generally not considered to be thread-safe and its methods should only be called within the context of the current thread. You should never try to call the methods of an NSRunLoop object running in a different thread, as doing so might cause unexpected results.

Tasks

Accessing Run Loops and Modes

• + currentRunLoop
• – currentMode
• – limitDateForMode:
• + mainRunLoop
• – getCFRunLoop

Managing Timers

• – addTimer:forMode:

Managing Ports

• – addPort:forMode:
• – removePort:forMode:

Configuring as Server Process

• – configureAsServer Deprecated in Mac OS X v10.5

Running a Loop

• – run
• – runMode:beforeDate:
• – runUntilDate:
• – acceptInputForMode:beforeDate:

Scheduling and Canceling Messages

• – performSelector:target:argument:order:modes:
• – cancelPerformSelector:target:argument:
• – cancelPerformSelectorsWithTarget:

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 Mac OS X v10.0 and later.

See Also

• – currentMode

Related Sample Code

• CocoaEcho
• CocoaSOAP
• OpenGLCompositorLab
• QTAudioExtractionPanel
• WhackedTV

Declared In

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 Mac OS X v10.5.

Declared In

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. Mac 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 Mac OS X v10.0 and later.

See Also

• – runMode:beforeDate:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – removePort:forMode:

Declared In

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 Mac OS X v10.0 and later.

Related Sample Code

• OpenGLCompositorLab
• Quartz Composer Live DV
• Quartz Composer QCTV
• Quartz Composer Texture
• WhackedTV

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.2 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• + currentRunLoop
• – limitDateForMode:
• – run
• – runUntilDate:

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – cancelPerformSelector:target:argument:

Related Sample Code

• StickiesExample

Declared In

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 Mac OS X v10.0 and later.

See Also

• – addPort:forMode:

Declared In

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. Mac 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 Mac OS X v10.0 and later.

See Also

• – runUntilDate:

Related Sample Code

• CocoaEcho
• CocoaHTTPServer
• CocoaSOAP
• SimpleThreads
• TrivialThreads

Declared In

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

NO without starting the run loop if there are no input sources in mode; otherwise YES.

Discussion

If no input sources or timers are attached to the run loop, this method exits immediately; 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 is not a guarantee that the run loop will exit. Mac 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 Mac OS X v10.0 and later.

See Also

• – run
• – runUntilDate:

Related Sample Code

• CocoaSOAP

Declared In

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. Mac 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 Mac OS X v10.0 and later.

See Also

• – run

Related Sample Code

• EnhancedAudioBurn
• QTAudioExtractionPanel

Declared In

Constants

Run Loop Modes

NSRunLoop defines the following run loop mode.

extern NSString *NSDefaultRunLoopMode;

Constants

NSDefaultRunLoopMode

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

This is the most commonly used run-loop mode.

Available in Mac OS X v10.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 Mac OS X v10.5 and later.

Declared in NSRunLoop.h.

Declared In

Additional run loop modes are defined by NSConnection and NSApplication.

Next Page > Hide TOC