iOS Developer Library

Developer

Foundation Framework Reference NSRunLoop Class Reference

Options
Deployment Target:

On This Page
Language:

NSRunLoop

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

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.

  • Returns the NSRunLoop object for the current thread.

    Declaration

    Swift

    class func currentRunLoop() -> NSRunLoop

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – currentMode

  • The receiver's current input mode. (read-only)

    Declaration

    Swift

    var currentMode: String? { get }

    Objective-C

    @property(readonly, copy) NSString *currentMode

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func limitDateForMode(_ mode: String) -> NSDate?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the run loop of the main thread.

    Declaration

    Swift

    class func mainRunLoop() -> NSRunLoop

    Objective-C

    + (NSRunLoop *)mainRunLoop

    Return Value

    An object representing the main thread’s run loop.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the receiver's underlying CFRunLoop Reference object.

    Declaration

    Swift

    func getCFRunLoop() -> CFRunLoop

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Registers a given timer with a given input mode.

    Declaration

    Swift

    func addTimer(_ aTimer: NSTimer, forMode mode: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func addPort(_ aPort: NSPort, forMode mode: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func removePort(_ aPort: NSPort, forMode mode: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func run()

    Objective-C

    - (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 NOfalse somewhere else in the program.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func runMode(_ mode: String, beforeDate limitDate: NSDate) -> Bool

    Objective-C

    - (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

    YEStrue if the run loop ran and processed an input source or if the specified timeout value was reached; otherwise, NOfalse 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 NOfalse; 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func runUntilDate(_ limitDate: NSDate)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – run

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

    Declaration

    Swift

    func acceptInputForMode(_ mode: String, beforeDate limitDate: NSDate)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Cancels the sending of a previously scheduled message.

    Declaration

    Swift

    func cancelPerformSelector(_ aSelector: Selector, target target: AnyObject, argument anArgument: AnyObject?)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Cancels all outstanding ordered performs scheduled with a given target.

    Declaration

    Swift

    func cancelPerformSelectorsWithTarget(_ target: AnyObject)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • NSRunLoop defines the following run loop mode.

    Declaration

    Swift

    let NSDefaultRunLoopMode: String let NSRunLoopCommonModes: String

    Objective-C

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

    Constants

    • NSDefaultRunLoopMode

      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.

    • NSRunLoopCommonModes

      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.