Up

NSRunLoop class reference

Authors

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

Version: 1.126

Date: 2005/11/28 15:41:33

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 NSRunLoop(mingw32) category
  6. Software documentation for the RunLoopEvents protocol

Software documentation for the NSRunLoop class

NSRunLoop : NSObject

Declared in:
Foundation/NSRunLoop.h
Conforms to:
GCFinalization
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.

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

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 anything watched for becomes useless. Returns that date/time.

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

NSObject(OptionalPortRunLoop)

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

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;
Availability: OpenStep

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
Availability: OpenStep

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;
Availability: OpenStep

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;
Availability: OpenStep

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
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: (unsigned int)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).
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;
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 NSRunLoop(mingw32) category

NSRunLoop(mingw32)

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

Obsolete interface that add method to set target for win32 messages.
Method summary

addMsgTarget: withMethod: forMode: 

- (void) addMsgTarget: (id)target withMethod: (SEL)selector forMode: (NSString*)mode;
Availability: OpenStep

Deprecated... will be removed

removeMsgForMode: 

- (void) removeMsgForMode: (NSString*)mode;
Availability: OpenStep

Deprecated... will be removed

Software documentation for the RunLoopEvents protocol

RunLoopEvents

Declared in:
Foundation/NSRunLoop.h
Availability: OpenStep

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;
Availability: OpenStep

Callback message sent to object when the event it it waiting for occurs. The 'data' and 'type' values 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. In the case of ET_WINMSG 'extra' is a pointer to a windows MSG structure containing the received event.

timedOutEvent: type: forMode: 

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

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