- Inherits from:
- NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- Foundation/NSRunLoop.h
The NSRunLoop class declares the programmatic interface to objects that manage input sources. An NSRunLoop processes input for sources such as mouse and keyboard events from the window system, NSPorts, NSTimers, and NSConnections.
In general, your application won't need to either create or explicitly manage NSRunLoop objects. Each thread has an NSRunLoop object automatically created for it. Each process begins with a default thread and therefore has a default run loop.
If you do want to perform your own explicit run loop management, you do so by accessing the current thread's run loop (returned by the class method currentRunLoop). You must specify two things: the input sources, which are the objects from which the run loop will receive information, and an input mode, which specifies the type of input to be received. NSRunLoop defines this input mode:
Input mode | Description |
NSDefaultRunLoopMode |
Use this mode to deal with input sources other than NSConnections. Defined in the Foundation/NSRunLoop.h header file. This is the most commonly used run loop mode. |
In addition, NSConnection defines this mode:
Input mode | Description |
NSConnectionReplyMode |
Use this mode to indicate NSConnection objects waiting for replies. Defined in the Foundation/NSConnection.h header file. You rarely need to use this mode. |
And the Application Kit defines these modes:
Additional input modes | Description |
NSModalPanelRunLoopMode |
Use this mode when waiting for input from a modal panel, such as NSSavePanel or NSOpenPanel. Defined in the AppKit/NSApplication.h header file. |
NSEventTrackingRunLoopMode |
Use this mode for event tracking loops. Defined in the AppKit/NSApplication.h header file. |
You associate a list of input sources with each input mode. There are two general types of input sources to a run loop: asynchronous (input arrives at unpredictable intervals) and synchronous (input arrives at regular intervals). NSPort objects represent asynchronous input sources, and NSTimer objects represent synchronous input sources. Each input source has a limit date associated with it. For NSPorts, the limit date is a timeout value, after which input from that port is no longer timely. For NSTimers, the limit date specifies when the timer should fire. (When a timer fires, it sends a specified message to a specified object, and it may be scheduled to fire again later. See the NSTimer class specification for more information.)
When an NSRunLoop runs, it polls each of the sources for the input mode to determine which one has the earliest limit date. During this polling, the input sources may process any input they have queued. Once the NSRunLoop determines the earliest limit date for this input mode, it waits for input from the operating system until that limit date. If input arrives, it is processed. At that point, the NSRunLoop may either return or it may continue, depending on which method was used to run the loop.
For example:
NSRunLoop *theLoop = [NSRunLoop currentRunLoop]; [theLoop acceptInputForMode:NSDefaultRunLoopMode beforeDate:[theLoop limitDateForMode:NSDefaultRunLoopMode]];
The method limitDateForMode: returns
the earliest limit date of all the input sources for the mode NSDefaultRunLoopMode
. acceptInputForMode:beforeDate: runs
the loop until that date, processing any input it receives until
that time. As a convenience, you can use runMode:beforeDate: instead. It invokes acceptInputForMode:beforeDate: and limitDateForMode: with
the mode you supply.
To continuously run in NSDefaultRunLoopMode
,
you can use either of the methods run or runUntilDate:. To run another mode
continuously, invoke runMode:beforeDate: in
a loop with a date far in the future:
while ([[NSRunLoop currentRunLoop] runMode:NSModalPanelRunLoopMode beforeDate:[NSDate distantFuture]]) ;
Note: Regardless of the date you specify in runMode:beforeDate:, a run loop with nothing to do (that is no sources from which to receive input) will exit immediately. You must add the input sources to the run loop mode before you start the run loop. |
- Accessing the current run loop
- + currentRunLoop
- - currentMode
- - limitDateForMode:
- - getCFRunLoop
- Managing timers
- - addTimer:forMode:
- Managing ports
- - addPort:forMode:
- - removePort:forMode:
- Setting up for server processes
- - configureAsServer
- Running a loop
- - run
- - runUntilDate:
- - runMode:beforeDate:
- - acceptInputForMode:beforeDate:
- Sending messages
- - performSelector:target:argument:order:modes:
- - cancelPerformSelector:target:argument:
+ (NSRunLoop *)currentRunLoop
See Also: - currentMode
- (void)acceptInputForMode:(NSString
*)mode
beforeDate:(NSDate *)limitDate
- (void)addPort:(NSPort
*)aPort
forMode:(NSString *)mode
See Also: - removePort:forMode:
- (void)addTimer:(NSTimer
*)aTimer
forMode:(NSString *)mode
- (void)cancelPerformSelector:(SEL)aSelector
target:(id)target
argument:(id)anArgument
- (void)configureAsServer
- (NSString *)currentMode
See Also: - currentRunLoop
- (CFRunLoopRef)getCFRunLoop
- (NSDate *)limitDateForMode:(NSString
*)mode
- (void)performSelector:(SEL)aSelector
target:(id)target
argument:(id)anArgument
order:(unsigned)order
modes:(NSArray *)modes
This method returns before the aSelector message is sent. The aSelector method should not have a significant return value and should take a single argument of type id. The NSRunLoop does not retain the target and anArgument objects.
Use this method is 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.
See Also: - cancelPerformSelector:target:argument:
- (void)removePort:(NSPort
*)aPort
forMode:(NSString *)mode
See Also: - addPort:forMode:
- (void)run
NSDefaultRunLoopMode
by
repeatedly invoking runMode:beforeDate: until
the limit dates for all input sources have passed.See Also: - runUntilDate:
- (BOOL)runMode:(NSString
*)mode
beforeDate:(NSDate *)limitDate
NO
without
starting the run loop if the limit dates for all of mode's input
sources have passed; otherwise returns YES
.- (void)runUntilDate:(NSDate
*)limitDate
NSDefaultRunLoopMode
by
repeatedly invoking runMode:beforeDate:until limitDate or
until the limit dates for all of the input sources have passed.See Also: - run