Up

NSRunLoop class reference

Authors

Andrew Kachites McCallum (mccallum@gnu.ai.mit.edu)
Richard Frith-Macdonald (richard@brainstorm.co.uk)

Version: 36523

Date: 2013-04-14 10:04:40 +0100 (Sun, 14 Apr 2013)

Copyright: (C) 1996-1999 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSRunLoop class
  2. Software documentation for the NSObject(RunLoopEvents) informal protocol
  3. Software documentation for the NSRunLoop(GNUstepExtensions) category
  4. Software documentation for the NSRunLoop(OPENSTEP) category
  5. Software documentation for the RunLoopEvents protocol

Software documentation for the NSRunLoop class

NSRunLoop : NSObject

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

NSRunLoop instances handle various utility tasks that must be performed repetitively in an application, such as processing input events, listening for distributed objects communications, firing NSTimer s, and sending notifications and other messages asynchronously.

There is one run loop per thread in an application, which may always be obtained through the +currentRunLoop method (you cannot use -init or +new), however unless you are using the AppKit and the NSApplication class, the run loop will not be started unless you explicitly send it a -run message.

At any given point, a run loop operates in a single mode, usually NSDefaultRunLoopMode. Other options include NSConnectionReplyMode, and certain modes used by the AppKit.

Method summary

currentRunLoop 

+ (NSRunLoop*) currentRunLoop;
Availability: OpenStep

Returns the run loop instance for the current thread.

acceptInputForMode: beforeDate: 

- (void) acceptInputForMode: (NSString*)mode beforeDate: (NSDate*)limit_date;
Availability: OpenStep

Listen for events from input sources.
If limit_date is nil or in the past, then don't wait; just poll inputs and return, otherwise block until input is available or until the earliest limit date has passed (whichever comes first).
If the supplied mode is nil, uses NSDefaultRunLoopMode.
If there are no input sources or timers in the mode, returns immediately.

addTimer: forMode: 

- (void) addTimer: (NSTimer*)timer forMode: (NSString*)mode;
Availability: OpenStep

Adds a timer to the loop in the specified mode.
Timers are removed automatically when they are invalid.

currentMode 

- (NSString*) currentMode;
Availability: OpenStep

Returns the current mode of this runloop. If the runloop is not running then this method returns nil.

limitDateForMode: 

- (NSDate*) limitDateForMode: (NSString*)mode;
Availability: OpenStep

Fires timers whose fire date has passed, and checks timers and limit dates for input sources, determining the earliest time that any future timeout becomes due. Returns that date/time.
Returns distant future if the loop contains no timers, just input sources without timeouts.
Returns nil if the loop contains neither timers nor input sources.

run 

- (void) run;
Availability: OpenStep

Runs the loop in NSDefaultRunLoopMode by repeated calls to -runMode:beforeDate: while there are still input sources. Exits when no more input sources remain.

runMode: beforeDate: 

- (BOOL) runMode: (NSString*)mode beforeDate: (NSDate*)date;
Availability: OpenStep

Calls -limitDateForMode: to determine if a timeout occurs before the specified date, then calls -acceptInputForMode:beforeDate: to run the loop once.
The specified date may be nil... in which case the loop runs until the limit date of the first input or timeout.
If the specified date is in the past, this runs the loop once only, to handle any events already available.
If there are no input sources or timers in mode, this method returns NO without running the loop (irrespective of the supplied date argument), otherwise returns YES.

runUntilDate: 

- (void) runUntilDate: (NSDate*)date;
Availability: OpenStep

Runs the loop in NSDefaultRunLoopMode by repeated calls to -runMode:beforeDate: while there are still input sources. Exits when no more input sources remain, or date is reached, whichever occurs first.

Software documentation for the NSObject(RunLoopEvents) informal protocol

NSObject(RunLoopEvents)

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

This informal protocol defiens optional methods of the run loop watcher.
Method summary

runLoopShouldBlock: 

- (BOOL) runLoopShouldBlock: (BOOL*)shouldTrigger;
Availability: OpenStep

Called by the run loop to find out whether it needs to block to wait for events for this watcher. The shouldTrigger flag is used to inform the run loop if tit should immediately trigger a received event for the watcher.

Software documentation for the NSRunLoop(GNUstepExtensions) category

NSRunLoop(GNUstepExtensions)

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

The run loop watcher API was originally intended to perform two tasks... 1. provide the most efficient API reasonably possible to integrate unix networking code into the runloop. 2. provide a standard mechanism to allow people to contribute code to add new I/O mechanisms to GNUstep (OpenStep didn't allow this). It succeeded in 1, and partially succeeded in 2 (adding support for the win32 API).
Method summary

addEvent: type: watcher: forMode: 

- (void) addEvent: (void*)data type: (RunLoopEventType)type watcher: (id<RunLoopEvents>)watcher forMode: (NSString*)mode;
Availability: OpenStep

Adds a watcher to the receiver... the watcher is used to monitor events of the specified type which are associted with the event handle data and it operates in the specified run loop modes.
The watcher remains in place until a corresponding call to -removeEvent:type:forMode:all: is made.

removeEvent: type: forMode: all: 

- (void) removeEvent: (void*)data type: (RunLoopEventType)type forMode: (NSString*)mode all: (BOOL)removeAll;
Availability: OpenStep

Removes a watcher from the receiver... the watcher must have been previously added using -addEvent:type:watcher:forMode:
This method mirrors exactly one addition of a watcher unless removeAll is YES, in which case it removes all additions of watchers matching the other paramters.

Software documentation for the NSRunLoop(OPENSTEP) category

NSRunLoop(OPENSTEP)

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

OpenStep-compatibility methods for NSRunLoop . These methods are also all in OS X.
Method summary

addPort: forMode: 

- (void) addPort: (NSPort*)port forMode: (NSString*)mode;
Availability: OpenStep

Adds port to be monitored in given mode.

cancelPerformSelector: target: argument: 

- (void) cancelPerformSelector: (SEL)aSelector target: (id)target argument: (id)argument;
Availability: OpenStep

Cancels any perform operations set up for the specified target in the receiver, but only if the value of aSelector and argument with which the performs were set up match those supplied.
Matching of the argument may be either by pointer equality or by use of the [NSObject -isEqual:] method.

cancelPerformSelectorsWithTarget: 

- (void) cancelPerformSelectorsWithTarget: (id)target;
Availability: OpenStep

Cancels any perform operations set up for the specified target in the receiver.

configureAsServer 

- (void) configureAsServer;
Availability: OpenStep

Configure event processing for acting as a server process for distributed objects. (In the current implementation this is a no-op.)

performSelector: target: argument: order: modes: 

- (void) performSelector: (SEL)aSelector target: (id)target argument: (id)argument order: (NSUInteger)order modes: (NSArray*)modes;
Availability: OpenStep

Sets up sending of aSelector to target with argument.
The selector is sent before the next runloop iteration (unless cancelled before then) in any of the specified modes.
The target and argument objects are retained.
The order value is used to determine the order in which messages are sent if multiple messages have been set up. Messages with a lower order value are sent first.
If the modes array is empty, this method has no effect.

removePort: forMode: 

- (void) removePort: (NSPort*)port forMode: (NSString*)mode;
Availability: OpenStep

Removes port to be monitored from given mode. Ports are also removed if they are detected to be invalid.

Software documentation for the RunLoopEvents protocol

RunLoopEvents

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

This protocol defines the mandatory interface a run loop watcher must provide in order for it to be notified of events occurring in the loop it is watching.
Optional methods are documented in the NSObject(RunLoopEvents) category.
Method summary

receivedEvent: type: extra: forMode: 

- (void) receivedEvent: (void*)data type: (RunLoopEventType)type extra: (void*)extra forMode: (NSString*)mode;
Availability: OpenStep

This is the message sent back to a watcher when an event is observed by the run loop.
The 'data', 'type' and 'mode' arguments are the same as the arguments passed to the -addEvent:type:watcher:forMode: method.
The 'extra' argument varies. For an ET_TRIGGER event, it is the same as the 'data' argument. For other events on unix it is the file descriptor associated with the event (which may be the same as the 'data' argument, but is not in the case of ET_RPORT).
For windows it will be the handle or the windows message assciated with the event.


Up