| Derived from | |
| Framework | CoreFoundation/CoreFoundation.h |
| Companion guide | Run Loops |
| Declared in | CFRunLoop.h |
A CFRunLoop object monitors sources of input to a task and dispatches control when they become ready for processing. Examples of input sources might include user input devices, network connections, periodic or time-delayed events, and asynchronous callbacks.
Three types of objects can be monitored by a run loop: sources (CFRunLoopSource Reference), timers (CFRunLoopTimer Reference), and observers (CFRunLoopObserver Reference). To receive callbacks when these objects need processing, you must first place these objects into a run loop with CFRunLoopAddSource, CFRunLoopAddTimer, or CFRunLoopAddObserver. You can later remove an object from the run loop (or invalidate it) to stop receiving its callback.
Run loops have different modes in which they can run. Each mode has its own set of objects that the run loop monitors while running in that mode. Core Foundation defines a default mode, kCFRunLoopDefaultMode, to hold objects that should be monitored while the application (or thread) is sitting idle. Additional modes are created automatically when an object is added to an unrecognized mode. Each run loop has its own independent set of modes.
Core Foundation also defines a special pseudo-mode kCFRunLoopCommonModes to hold objects that should be shared by a set of “common” modes. A mode is added to the set of “common” modes by calling CFRunLoopAddCommonMode. The default mode, kCFRunLoopDefaultMode, is always a member of the set of common modes. The kCFRunLoopCommonModes constant is never passed to CFRunLoopRunInMode. Each run loop has its own independent set of common modes.
There is exactly one run loop per thread. You neither create nor destroy a thread’s run loop. Core Foundation automatically creates it for you as needed. You obtain the current thread’s run loop with CFRunLoopGetMain. Call CFRunLoopRun to run the current thread’s run loop in the default mode until the run loop is stopped with CFRunLoopStop. You can also call CFRunLoopRunInMode to run the current thread’s run loop in a specified mode for a set period of time (or until the run loop is stopped). A run loop can only run if the requested mode has at least one source or timer to monitor.
Run loops can be run recursively. You can call CFRunLoopRun or CFRunLoopRunInMode from within any run loop callout and create nested run loop activations on the current thread’s call stack. You are not restricted in which modes you can run from within a callout. You can create another run loop activation running in any available run loop mode, including any modes already running higher in the call stack.
Cocoa and Carbon each build upon CFRunLoop to implement their own higher-level event loop. When writing a Cocoa or Carbon application, you can add your sources, timers, and observers to their run loop objects and modes. Your objects will then get monitored as part of the regular application event loop. Use the NSRunLoop instance method getCFRunLoop to obtain the CFRunLoop corresponding to a Cocoa run loop. In Carbon applications, use the GetCFRunLoopFromEventLoop function.
Adds a mode to the set of run loop common modes.
void CFRunLoopAddCommonMode ( CFRunLoopRef rl, CFStringRef mode );
The run loop to modify. Each run loop has its own independent list of modes that are in the set of common modes.
The run loop mode to add to the set of common modes of rl.
Sources, timers, and observers get registered to one or more run loop modes and only run when the run loop is running in one of those modes. Common modes are a set of run loop modes for which you can define a set of sources, timers, and observers that are shared by these modes. Instead of registering a source, for example, to each specific run loop mode, you can register it once to the run loop’s common pseudo-mode and it will be automatically registered in each run loop mode in the common mode set. Likewise, when a mode is added to the set of common modes, any sources, timers, or observers already registered to the common pseudo-mode are added to the newly added common mode.
Once a mode is added to the set of common modes, it cannot be removed.
The Add, Contains, and Remove functions for sources, timers, and observers operate on a run loop’s set of common modes when you use the constant kCFRunLoopCommonModes for the run loop mode.
CFRunLoop.hAdds a CFRunLoopObserver object to a run loop mode.
void CFRunLoopAddObserver ( CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode );
The run loop to modify.
The run loop observer to add.
The run loop mode to which to add observer. Use the constant kCFRunLoopCommonModes to add observer to the set of objects monitored by all the common modes.
A run loop observer can be registered in only one run loop at a time, although it can be added to multiple run loop modes within that run loop.
If rl already contains observer in mode, this function does nothing.
CFRunLoop.hAdds a CFRunLoopSource object to a run loop mode.
void CFRunLoopAddSource ( CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode );
The run loop to modify.
The run loop source to add.
The run loop mode to which to add source. Use the constant kCFRunLoopCommonModes to add source to the set of objects monitored by all the common modes.
If source is a version 0 source, this function calls the schedule callback function specified in the context structure for source. See CFRunLoopSourceContext for more details.
A run loop source can be registered in multiple run loops and run loop modes at the same time. When the source is signaled, whichever run loop that happens to detect the signal first will fire the source.
If rl already contains source in mode, this function does nothing.
CFRunLoop.hAdds a CFRunLoopTimer object to a run loop mode.
void CFRunLoopAddTimer ( CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode );
The run loop to modify.
The run loop timer to add.
The run loop mode of rl to which to add timer. Use the constant kCFRunLoopCommonModes to add timer to the set of objects monitored by all the common modes.
A run loop timer can be registered in only one run loop at a time, although it can be added to multiple run loop modes within that run loop.
If rl already contains timer in mode, this function does nothing.
CFRunLoop.hReturns a Boolean value that indicates whether a run loop mode contains a particular CFRunLoopObserver object.
Boolean CFRunLoopContainsObserver ( CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode );
The run loop to examine.
The run loop observer for which to search.
The run loop mode in which to search for observer. Use the constant kCFRunLoopCommonModes to search for observer in the set of objects monitored by all the common modes.
true if observer is in mode mode of the run loop rl, otherwise false.
If observer was added to kCFRunLoopCommonModes, this function returns true if mode is either kCFRunLoopCommonModes or any of the modes that has been added to the set of common modes.
CFRunLoop.hReturns a Boolean value that indicates whether a run loop mode contains a particular CFRunLoopSource object.
Boolean CFRunLoopContainsSource ( CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode );
The run loop to examine.
The run loop source for which to search.
The run loop mode of rl in which to search. Use the constant kCFRunLoopCommonModes to search for source in the set of objects monitored by all the common modes.
true if source is in mode mode of the run loop rl, otherwise false.
If source was added to kCFRunLoopCommonModes, this function returns true if mode is either kCFRunLoopCommonModes or any of the modes that has been added to the set of common modes.
CFRunLoop.hReturns a Boolean value that indicates whether a run loop mode contains a particular CFRunLoopTimer object.
Boolean CFRunLoopContainsTimer ( CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode );
The run loop to examine.
The run loop timer for which to search.
The run loop mode of rl in which to search for timer. Use the constant kCFRunLoopCommonModes to search for timer in the set of objects monitored by all the common modes.
true if timer is in mode mode of the run loop rl, false otherwise.
If timer was added to kCFRunLoopCommonModes, this function returns true if mode is either kCFRunLoopCommonModes or any of the modes that has been added to the set of common modes.
CFRunLoop.hReturns an array that contains all the defined modes for a CFRunLoop object.
CFArrayRef CFRunLoopCopyAllModes ( CFRunLoopRef rl );
The run loop to examine.
An array that contains all the run loop modes defined for rl. Ownership follows the Create Rule.
CFRunLoop.hReturns the name of the mode in which a given run loop is currently running.
CFStringRef CFRunLoopCopyCurrentMode ( CFRunLoopRef rl );
The run loop to examine.
The mode in which rl is currently running; NULL if rl is not running. Ownership follows the Create Rule.
When run on the current thread’s run loop, the returned value identifies the run loop mode that made the callout in which your code is currently executing.
CFRunLoop.hReturns the CFRunLoop object for the current thread.
CFRunLoopRef CFRunLoopGetCurrent ( void );
Current thread’s run loop. Ownership follows the Get Rule.
Each thread has exactly one run loop associated with it.
CFRunLoop.hReturns the main CFRunLoop object.
CFRunLoopRef CFRunLoopGetMain ( void );
The main run loop. Ownership follows the Get Rule.
CFRunLoop.hReturns the time at which the next timer will fire.
CFAbsoluteTime CFRunLoopGetNextTimerFireDate ( CFRunLoopRef rl, CFStringRef mode );
The run loop to examine.
The run loop mode within rl to test.
The earliest firing time of the run loop timers registered in mode for the run loop rl.
CFRunLoop.hReturns the type identifier for the CFRunLoop opaque type.
CFTypeID CFRunLoopGetTypeID ( void );
The type identifier for the CFRunLoop opaque type.
CFRunLoop.hReturns a Boolean value that indicates whether the run loop is waiting for an event.
Boolean CFRunLoopIsWaiting ( CFRunLoopRef rl );
The run loop to examine.
true if rl has no events to process and is blocking, waiting for a source or timer to become ready to fire; false if rl either is not running or is currently processing a source, timer, or observer.
This function is useful only to test the state of another thread’s run loop. When called with the current thread’s run loop, this function always returns false.
CFRunLoop.hEnqueues a Block on a given runloop to be executed as the runloop cycles in specified modes.
void CFRunLoopPerformBlock ( CFRunLoopRef rl, CFTypeRef mode, void (^block)(void) );
A run loop.
A CFString that identifies a runloop mode, or a CFArray of CFStrings that each identify a runloop mode.
The Block to execute.
The Block is copied by the function before the function returns.
When the runloop is run in the mode or one of the modes specified by mode, the Block is executed. You can use this function as a means to get work “onto” another thread (similar to Cocoa’s performSelector:onThread:withObject:waitUntilDone: and related methods) as an alternative to mechanisms such as putting a CFRunLoopTimer in the other thread's run loop, or using CFMessagePort to pass information between threads.
CFRunLoop.hRemoves a CFRunLoopObserver object from a run loop mode.
void CFRunLoopRemoveObserver ( CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode );
The run loop to modify.
The run loop observer to remove.
The run loop mode of rl from which to remove observer. Use the constant kCFRunLoopCommonModes to remove observer from the set of objects monitored by all the common modes.
If rl does not contain observer in mode, this function does nothing.
CFRunLoop.hRemoves a CFRunLoopSource object from a run loop mode.
void CFRunLoopRemoveSource ( CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode );
The run loop to modify.
The run loop source to remove.
The run loop mode of rl from which to remove source. Use the constant kCFRunLoopCommonModes to remove source from the set of objects monitored by all the common modes.
If source is a version 0 source, this function calls the cancel callback function specified in the context structure for source. See CFRunLoopSourceContext and CFRunLoopSourceContext1for more details.
If rl does not contain source in mode, this function does nothing.
CFRunLoop.hRemoves a CFRunLoopTimer object from a run loop mode.
void CFRunLoopRemoveTimer ( CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode );
The run loop to modify.
The run loop timer to remove.
The run loop mode of rl from which to remove timer. Use the constant kCFRunLoopCommonModes to remove timer from the set of objects monitored by all the common modes.
If rl does not contain timer in mode, this function does nothing.
CFRunLoop.hRuns the current thread’s CFRunLoop object in its default mode indefinitely.
void CFRunLoopRun ( void );
The current thread’s run loop runs in the default mode (see “Default Run Loop Mode”) until the run loop is stopped with CFRunLoopStop or all the sources and timers are removed from the default run loop mode.
Run loops can be run recursively. You can call CFRunLoopRun from within any run loop callout and create nested run loop activations on the current thread’s call stack.
CFRunLoop.hRuns the current thread’s CFRunLoop object in a particular mode.
SInt32 CFRunLoopRunInMode ( CFStringRef mode, CFTimeInterval seconds, Boolean returnAfterSourceHandled );
The run loop mode to run. mode can be any arbitrary CFString. You do not need to explicitly create a run loop mode, although a run loop mode needs to contain at least one source or timer to run.
The length of time to run the run loop. If 0, only one pass is made through the run loop before returning; if multiple sources or timers are ready to fire immediately, only one (possibly two if one is a version 0 source) will be fired, regardless of the value of returnAfterSourceHandled.
A flag indicating whether the run loop should exit after processing one source. If false, the run loop continues processing events until seconds has passed.
A value indicating the reason the run loop exited. Possible values are described below.
Run loops can be run recursively. You can call CFRunLoopRunInMode from within any run loop callout and create nested run loop activations on the current thread’s call stack. You are not restricted in which modes you can run from within a callout. You can create another run loop activation running in any available run loop mode, including any modes already running higher in the call stack.
The run loop exits with the following return values under the indicated conditions:
kCFRunLoopRunFinished. The run loop mode mode has no sources or timers.
kCFRunLoopRunStopped. The run loop was stopped with CFRunLoopStop.
kCFRunLoopRunTimedOut. The time interval seconds passed.
kCFRunLoopRunHandledSource. A source was processed. This exit condition only applies when returnAfterSourceHandled is true.
CFRunLoop.hForces a CFRunLoop object to stop running.
void CFRunLoopStop ( CFRunLoopRef rl );
The run loop to stop.
This function forces rl to stop running and return control to the function that called CFRunLoopRun or CFRunLoopRunInMode for the current run loop activation. If the run loop is nested with a callout from one activation starting another activation running, only the innermost activation is exited.
CFRunLoop.hWakes a waiting CFRunLoop object.
void CFRunLoopWakeUp ( CFRunLoopRef rl );
The run loop to wake up.
A run loop goes to sleep when it is waiting for a source or timer to become ready to fire. If no source or timer fires, the run loop stays there until it times out or is explicitly woken up. If a run loop is modified, such as a new source added, you need to wake up the run loop to allow it to process the change. Version 0 sources use CFRunLoopWakeUp to cause the run loop to wake up after setting a source to be signaled, if they want the source handled immediately.
CFRunLoop.hA reference to a run loop object.
typedef struct __CFRunLoop *CFRunLoopRef;
CFRunLoop.hReturn codes for CFRunLoopRunInMode, identifying the reason the run loop exited.
enum {
kCFRunLoopRunFinished = 1,
kCFRunLoopRunStopped = 2,
kCFRunLoopRunTimedOut = 3,
kCFRunLoopRunHandledSource = 4
};
kCFRunLoopRunFinishedThe running run loop mode has no sources or timers to process.
Available in Mac OS X v10.0 and later.
Declared in CFRunLoop.h.
kCFRunLoopRunStoppedCFRunLoopStop was called on the run loop.
Available in Mac OS X v10.0 and later.
Declared in CFRunLoop.h.
kCFRunLoopRunTimedOutThe specified time interval for running the run loop has passed.
Available in Mac OS X v10.0 and later.
Declared in CFRunLoop.h.
kCFRunLoopRunHandledSourceA source has been processed. This value is returned only if the run loop was told to run only until a source was processed.
Available in Mac OS X v10.0 and later.
Declared in CFRunLoop.h.
A run loop pseudo-mode that manages objects monitored in the “common” modes.
const CFStringRef kCFRunLoopCommonModes;
kCFRunLoopCommonModesObjects added to a run loop using this value as the mode are monitored by all run loop modes that have been declared as a member of the set of “common” modes with CFRunLoopAddCommonMode.
Available in Mac OS X v10.0 and later.
Declared in CFRunLoop.h.
Run loops never run in this mode. This pseudo-mode is used only as a special set of sources, timers, and observers that is shared by other modes. See “Managing Observers” for more details.
Default run loop mode.
const CFStringRef kCFRunLoopDefaultMode;
kCFRunLoopDefaultModeRun loop mode that should be used when a thread is in its default, or idle, state, waiting for an event. This mode is used when the run loop is started with CFRunLoopRun.
Available in Mac OS X v10.0 and later.
Declared in CFRunLoop.h.
Last updated: 2009-05-16