Up
Authors
- Andrew Kachites McCallum (
mccallum@gnu.ai.mit.edu)
-
- Richard Frith-Macdonald (
richard@brainstorm.co.uk)
-
Date: Generated at 2023-12-20 19:35:39 -0500
Copyright: (C) 1996-1999 Free Software Foundation, Inc.
- 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
+ (
NSRunLoop*)
currentRunLoop;
Availability: OpenStep
Returns the run loop instance for the current
thread.
+ (
NSRunLoop*)
mainRunLoop;
Availability: MacOS-X 10.5.0
Returns the run loop instance of the main thread.
- (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 fire timers, poll inputs
and return, otherwise block (firing timers when they
are due) 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.
- (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.
- (
NSString*)
currentMode;
Availability: OpenStep
Returns the current mode of this runloop. If the
runloop is not running then this method returns
nil.
- (
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.
- (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.
- (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.
- (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.
- Declared in:
- Foundation/NSRunLoop.h
Availability: OpenStep
This informal protocol defiens optional methods of the
run loop watcher.
Method summary
- (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.
- 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
- (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 is not retained, but remains in
place until a corresponding call to
-removeEvent:type:forMode:all:
is made. If is the watchers responsibility to ensure
that it is removed from the run loop safely.
- (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.
- Declared in:
- Foundation/NSRunLoop.h
Availability: OpenStep
OpenStep-compatibility methods for
NSRunLoop
. These methods are also all in OS X.
- (void)
addPort: (
NSPort*)port
forMode: (
NSString*)mode;
Availability: OpenStep
Adds port to be monitored in given
mode.
- (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.
- (void)
cancelPerformSelectorsWithTarget: (id)target;
Availability: OpenStep
Cancels any perform operations set up for the
specified target in the receiver.
- (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.)
- (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.
- (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.
- 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
- (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