Up

NSRunLoop class reference

Authors

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

Version: 1.115

Date: 2004/07/29 15:30:47

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


Contents -

  1. Software documentation for the NSRunLoop class
  2. Software documentation for the NSObject(OptionalPortRunLoop) 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
Conforms to:
GCFinalization
Standards:

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.

In general, there is one run loop per thread in an application, which may always be obtained through the +currentRunLoop method, 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;

Returns the run loop instance for the current thread.


acceptInputForMode: beforeDate: 

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

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.


addTimer: forMode: 

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

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


currentMode 

- (NSString*) currentMode;

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


limitDateForMode: 

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

Fires timers whose fire date has passed, and checks timers and limit dates for input sources, determining the earliest time that anything watched for becomes useless. Returns that date/time.


run 

- (void) run;

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;

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, runs the loop once only, to handle any events already available.
If there are no input sources in mode, returns NO without running the loop, otherwise returns YES.


runUntilDate: 

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

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(OptionalPortRunLoop) informal protocol

NSObject(OptionalPortRunLoop)

Declared in:
Foundation/NSRunLoop.h
Standards:

Defines implementation-helper method -getFds:count: . This interface will probably change. Do not rely on it.

Method summary

getFds: count: 

- (void) getFds: (int*)fds count: (int*)count;

If a InPort object responds to this, it is sent just before we are about to wait listening for input. This interface will probably change.


Software documentation for the NSRunLoop(GNUstepExtensions) category

NSRunLoop(GNUstepExtensions)

Declared in:
Foundation/NSRunLoop.h
Standards:

These are general purpose methods for letting objects ask the runloop to watch for events for them. Only one object at a time may be watching for a particular event in a mode, but that object may add itself as a watcher many times as long as each addition is matched by a removal (the run loop keeps count). Alternatively, the 'removeAll' parameter may be set to 'YES' for [-removeEvent:type:forMode:all:] in order to remove the watcher irrespective of the number of times it has been added.

Method summary

addEvent: type: watcher: forMode: 

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

Adds a runloop watcher matching the specified data and type in this runloop. If the mode is nil, either the -currentMode is used (if the loop is running) or NSDefaultRunLoopMode is used.
NB. The watcher is not retained by the run loop and must be removed from the loop before deallocation... otherwise the loop might try to send a message to the deallocated watcher object resulting in a crash. You use -removeEvent:type:forMode:all: to do this.


removeEvent: type: forMode: all: 

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

Removes a runloop watcher matching the specified data and type in this runloop. If the mode is nil, either the -currentMode is used (if the loop is running) or NSDefaultRunLoopMode is used.
The additional removeAll flag may be used to remove all instances of the watcher rather than just a single one.


Software documentation for the NSRunLoop(OPENSTEP) category

NSRunLoop(OPENSTEP)

Declared in:
Foundation/NSRunLoop.h
Standards:

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

Method summary

addPort: forMode: 

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

Adds port to be monitored in given mode.


cancelPerformSelector: target: argument: 

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

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;

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


configureAsServer 

- (void) configureAsServer;

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: (unsigned int)order modes: (NSArray*)modes;

Sets up sending of aSelector to target with argument.
The selector is sent before the next runloop iteration (unless cancelled before then).
The target and argument objects are not 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.


removePort: forMode: 

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

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
Standards:

This protocol documents the callback messages that an object receives if it has registered to receive run loop events using [NSRunLoop -addEvent:type:watcher:forMode:]

Method summary

receivedEvent: type: extra: forMode: 

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

Callback message sent to object when the event it it waiting for occurs. The 'data' and 'type' valueds are those passed in the original -addEvent:type:watcher:forMode: method. The 'extra' value may be additional data returned depending on the type of event.


timedOutEvent: type: forMode: 

- (NSDate*) timedOutEvent: (void*)data type: (RunLoopEventType)type forMode: (NSString*)mode;

Callback message sent to object waiting for an event in the runloop when the limit-date for the operation is reached. If an NSDate object is returned, the operation is restarted with the new limit-date, otherwise it is removed from the run loop.



Up