Class: NSRunLoop

Inherits:
NSObject show all

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.

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (NSRunLoop) currentRunLoop

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

Returns:

+ (NSRunLoop) mainRunLoop

Returns the run loop of the main thread.

Returns:

  • (NSRunLoop) —

    An object representing the main thread’s run loop.

Instance Method Details

- (Object) acceptInputForMode(mode, beforeDate:limitDate)

Runs the loop once or until the specified date, accepting input only for the specified mode. 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. Note: A timer is not considered an input source and may fire multiple times while waiting for this method to returnManually 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.

Parameters:

  • mode (String) —

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

  • limitDate (NSDate) —

    The date up until which to run.

Returns:

- (Object) addPort(aPort, forMode:mode)

Adds a port as an input source to the specified mode of the run loop. 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.

Parameters:

  • aPort (NSPort) —

    The port to add to the receiver.

  • mode (String) —

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

Returns:

- (Object) addTimer(aTimer, forMode:mode)

Registers a given timer with a given input mode. 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.

Parameters:

  • aTimer (NSTimer) —

    The timer to register with the receiver.

  • mode (String) —

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

Returns:

- (Object) cancelPerformSelector(aSelector, target:target, argument:anArgument)

Cancels the sending of a previously scheduled message. 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.

Parameters:

  • aSelector (Symbol) —

    The previously-specified selector.

  • target (Object) —

    The previously-specified target.

  • anArgument (Object) —

    The previously-specified argument.

Returns:

- (Object) cancelPerformSelectorsWithTarget(target)

Cancels all outstanding ordered performs scheduled with a given target. 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.

Parameters:

  • target (Object) —

    The previously-specified target.

Returns:

- (String) currentMode

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

Returns:

  • (String) —

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

- (CFRunLoopRef) getCFRunLoop

Returns the receiver's underlying CFRunLoop Reference object. 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.

Returns:

  • (CFRunLoopRef) —

    The receiver's underlying CFRunLoop Reference object.

- (NSDate) limitDateForMode(mode)

Performs one pass through the run loop in the specified mode and returns the date at which the next timer is scheduled to fire. 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.

Parameters:

  • mode (String) —

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

Returns:

  • (NSDate) —

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

- (Object) performSelector(aSelector, target:target, argument:anArgument, order:order, modes:modes)

Schedules the sending of a message on the current run loop. 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.

Parameters:

  • aSelector (Symbol) —

    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 (Object) —

    The object that defines the selector in aSelector.

  • anArgument (Object) —

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

  • order (Integer) —

    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 (Array) —

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

Returns:

- (Object) removePort(aPort, forMode:mode)

Removes a port from the specified input mode of the run loop. If you added the port to multiple input modes, you must remove it from each mode separately.

Parameters:

  • aPort (NSPort) —

    The port to remove from the receiver.

  • mode (String) —

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

Returns:

- (Object) run

Puts the receiver into a permanent loop, during which time it processes data from all attached input sources. 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:where shouldKeepRunning is set to NO somewhere else in the program.

Returns:

- (Boolean) runMode(mode, beforeDate:limitDate)

Runs the loop once, blocking for input in the specified mode until a given date. 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. Note: A timer is not considered an input source and may fire multiple times while waiting for this method to return

Parameters:

  • mode (String) —

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

  • limitDate (NSDate) —

    The date until which to block.

Returns:

  • (Boolean) —

    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.

- (Object) runUntilDate(limitDate)

Runs the loop until the specified date, during which time it processes data from all attached input sources. 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.

Parameters:

  • limitDate (NSDate) —

    The date up until which to run.

Returns: