Mac Developer Library

Developer

CoreFoundation Framework Reference CFRunLoop Reference

Options
Deployment Target:

On This Page
Language:

CFRunLoop Reference

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.

Each source, timer, and observer added to a run loop must be associated with one or more run loop modes. Modes determine what events are processed by the run loop during a given iteration. Each time the run loop executes, it does so in a specific mode. While in that mode, the run loop processes only the events associated with sources, timers, and observers associated with that mode. You assign most sources to the default run loop mode (designated by the kCFRunLoopDefaultMode constant), which is used to process events when the application (or thread) is idle. However, the system defines other modes and may execute the run loop in those other modes to limit which sources, timers, and observers are processed. Because run-loop modes are simply specified as strings, you can also define your own custom modes to limit the processing of events

Core Foundation defines a special pseudo-mode, called the common modes, that allow you to associate more than one mode with a given source, timer, or observer. To specify the common modes, use the kCFRunLoopCommonModes constant for the mode when configuring the object. Each run loop has its own independent set of common modes and the default mode (kCFRunLoopDefaultMode) is always a member of the set. To add a mode to the set of common modes, use the CFRunLoopAddCommonMode function.

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 CFRunLoopGetCurrent. 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 applications build upon CFRunLoop to implement their own higher-level event loop. When writing an 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 getCFRunLoop method of NSRunLoop to obtain the corresponding CFRunLoopRef type. In Carbon applications, use the GetCFRunLoopFromEventLoop function.

For more information about how run loops behave, see Run Loops in Threading Programming Guide.

Functions

  • Runs the current thread’s CFRunLoop object in its default mode indefinitely.

    Declaration

    Swift

    func CFRunLoopRun()

    Objective-C

    void CFRunLoopRun ( void );

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Runs the current thread’s CFRunLoop object in a particular mode.

    Declaration

    Swift

    func CFRunLoopRunInMode(_ mode: CFString!, _ seconds: CFTimeInterval, _ returnAfterSourceHandled: Boolean) -> Int32

    Objective-C

    SInt32 CFRunLoopRunInMode ( CFStringRef mode, CFTimeInterval seconds, Boolean returnAfterSourceHandled );

    Parameters

    mode

    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.

    seconds

    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.

    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.

    Return Value

    A value indicating the reason the run loop exited. Possible values are described below.

    Discussion

    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.

    You must not specify the kCFRunLoopCommonModes constant for the mode parameter. Run loops always run in a specific mode. You specify the common modes only when configuring a run-loop observer and only in situations where you want that observer to run in more than one mode.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Wakes a waiting CFRunLoop object.

    Declaration

    Swift

    func CFRunLoopWakeUp(_ rl: CFRunLoop!)

    Objective-C

    void CFRunLoopWakeUp ( CFRunLoopRef rl );

    Parameters

    rl

    The run loop to wake up.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Forces a CFRunLoop object to stop running.

    Declaration

    Swift

    func CFRunLoopStop(_ rl: CFRunLoop!)

    Objective-C

    void CFRunLoopStop ( CFRunLoopRef rl );

    Parameters

    rl

    The run loop to stop.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the run loop is waiting for an event.

    Declaration

    Swift

    func CFRunLoopIsWaiting(_ rl: CFRunLoop!) -> Boolean

    Objective-C

    Boolean CFRunLoopIsWaiting ( CFRunLoopRef rl );

    Parameters

    rl

    The run loop to examine.

    Return Value

    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.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Adds a CFRunLoopSource object to a run loop mode.

    Declaration

    Swift

    func CFRunLoopAddSource(_ rl: CFRunLoop!, _ source: CFRunLoopSource!, _ mode: CFString!)

    Objective-C

    void CFRunLoopAddSource ( CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode );

    Parameters

    rl

    The run loop to modify.

    source

    The run loop source to add. The source is retained by the run loop.

    mode

    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.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a run loop mode contains a particular CFRunLoopSource object.

    Declaration

    Swift

    func CFRunLoopContainsSource(_ rl: CFRunLoop!, _ source: CFRunLoopSource!, _ mode: CFString!) -> Boolean

    Objective-C

    Boolean CFRunLoopContainsSource ( CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode );

    Parameters

    rl

    The run loop to examine.

    source

    The run loop source for which to search.

    mode

    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.

    Return Value

    true if source is in mode mode of the run loop rl, otherwise false.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Removes a CFRunLoopSource object from a run loop mode.

    Declaration

    Swift

    func CFRunLoopRemoveSource(_ rl: CFRunLoop!, _ source: CFRunLoopSource!, _ mode: CFString!)

    Objective-C

    void CFRunLoopRemoveSource ( CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode );

    Parameters

    rl

    The run loop to modify.

    source

    The run loop source to remove.

    mode

    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.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Adds a CFRunLoopObserver object to a run loop mode.

    Declaration

    Swift

    func CFRunLoopAddObserver(_ rl: CFRunLoop!, _ observer: CFRunLoopObserver!, _ mode: CFString!)

    Objective-C

    void CFRunLoopAddObserver ( CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode );

    Parameters

    rl

    The run loop to modify.

    observer

    The run loop observer to add.

    mode

    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.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a run loop mode contains a particular CFRunLoopObserver object.

    Declaration

    Swift

    func CFRunLoopContainsObserver(_ rl: CFRunLoop!, _ observer: CFRunLoopObserver!, _ mode: CFString!) -> Boolean

    Objective-C

    Boolean CFRunLoopContainsObserver ( CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode );

    Parameters

    rl

    The run loop to examine.

    observer

    The run loop observer for which to search.

    mode

    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.

    Return Value

    true if observer is in mode mode of the run loop rl, otherwise false.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Removes a CFRunLoopObserver object from a run loop mode.

    Declaration

    Swift

    func CFRunLoopRemoveObserver(_ rl: CFRunLoop!, _ observer: CFRunLoopObserver!, _ mode: CFString!)

    Objective-C

    void CFRunLoopRemoveObserver ( CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode );

    Parameters

    rl

    The run loop to modify.

    observer

    The run loop observer to remove.

    mode

    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.

    Discussion

    If rl does not contain observer in mode, this function does nothing.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Adds a mode to the set of run loop common modes.

    Declaration

    Swift

    func CFRunLoopAddCommonMode(_ rl: CFRunLoop!, _ mode: CFString!)

    Objective-C

    void CFRunLoopAddCommonMode ( CFRunLoopRef rl, CFStringRef mode );

    Parameters

    rl

    The run loop to modify. Each run loop has its own independent list of modes that are in the set of common modes.

    mode

    The run loop mode to add to the set of common modes of rl.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an array that contains all the defined modes for a CFRunLoop object.

    Declaration

    Swift

    func CFRunLoopCopyAllModes(_ rl: CFRunLoop!) -> CFArray!

    Objective-C

    CFArrayRef CFRunLoopCopyAllModes ( CFRunLoopRef rl );

    Parameters

    rl

    The run loop to examine.

    Return Value

    An array that contains all the run loop modes defined for rl. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the name of the mode in which a given run loop is currently running.

    Declaration

    Swift

    func CFRunLoopCopyCurrentMode(_ rl: CFRunLoop!) -> CFString!

    Objective-C

    CFStringRef CFRunLoopCopyCurrentMode ( CFRunLoopRef rl );

    Parameters

    rl

    The run loop to examine.

    Return Value

    The mode in which rl is currently running; NULL if rl is not running. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Adds a CFRunLoopTimer object to a run loop mode.

    Declaration

    Swift

    func CFRunLoopAddTimer(_ rl: CFRunLoop!, _ timer: CFRunLoopTimer!, _ mode: CFString!)

    Objective-C

    void CFRunLoopAddTimer ( CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode );

    Parameters

    rl

    The run loop to modify.

    timer

    The run loop timer to add.

    mode

    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.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the time at which the next timer will fire.

    Declaration

    Swift

    func CFRunLoopGetNextTimerFireDate(_ rl: CFRunLoop!, _ mode: CFString!) -> CFAbsoluteTime

    Objective-C

    CFAbsoluteTime CFRunLoopGetNextTimerFireDate ( CFRunLoopRef rl, CFStringRef mode );

    Parameters

    rl

    The run loop to examine.

    mode

    The run loop mode within rl to test.

    Return Value

    The earliest firing time of the run loop timers registered in mode for the run loop rl.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Removes a CFRunLoopTimer object from a run loop mode.

    Declaration

    Swift

    func CFRunLoopRemoveTimer(_ rl: CFRunLoop!, _ timer: CFRunLoopTimer!, _ mode: CFString!)

    Objective-C

    void CFRunLoopRemoveTimer ( CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode );

    Parameters

    rl

    The run loop to modify.

    timer

    The run loop timer to remove.

    mode

    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.

    Discussion

    If rl does not contain timer in mode, this function does nothing.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a run loop mode contains a particular CFRunLoopTimer object.

    Declaration

    Swift

    func CFRunLoopContainsTimer(_ rl: CFRunLoop!, _ timer: CFRunLoopTimer!, _ mode: CFString!) -> Boolean

    Objective-C

    Boolean CFRunLoopContainsTimer ( CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode );

    Parameters

    rl

    The run loop to examine.

    timer

    The run loop timer for which to search.

    mode

    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.

    Return Value

    true if timer is in mode mode of the run loop rl, false otherwise.

    Discussion

    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.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Enqueues a block object on a given runloop to be executed as the runloop cycles in specified modes.

    Declaration

    Swift

    func CFRunLoopPerformBlock(_ rl: CFRunLoop!, _ mode: AnyObject!, _ block: (() -> Void)!)

    Objective-C

    void CFRunLoopPerformBlock ( CFRunLoopRef rl, CFTypeRef mode, void (^block)(void) );

    Parameters

    rl

    A run loop.

    mode

    A CFString that identifies a runloop mode, or a CFArray of CFStrings that each identify a runloop mode.

    block

    The block object to execute.

    The block is copied by the function before the function returns.

    Discussion

    When the runloop runs in the specified mode, the block object is executed. You can use this function as a means to offload work to another thread similar to Cocoa’s performSelector:onThread:withObject:waitUntilDone: and related methods. You can also use it 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.

    This method enqueues the block only and does not automatically wake up the specified run loop. Therefore, execution of the block occurs the next time the run loop wakes up to handle another input source. If you want the work performed right away, you must explicitly wake up that thread using the CFRunLoopWakeUp function.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.6 and later.

  • Returns the type identifier for the CFRunLoop opaque type.

    Declaration

    Swift

    func CFRunLoopGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFRunLoopGetTypeID ( void );

    Return Value

    The type identifier for the CFRunLoop opaque type.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

  • A reference to a run loop object.

    Declaration

    Swift

    typealias CFRunLoopRef = CFRunLoop

    Objective-C

    typedef struct __CFRunLoop *CFRunLoopRef;

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Constants

Miscellaneous

  • Return codes for CFRunLoopRunInMode, identifying the reason the run loop exited.

    Declaration

    Swift

    var kCFRunLoopRunFinished: Int { get } var kCFRunLoopRunStopped: Int { get } var kCFRunLoopRunTimedOut: Int { get } var kCFRunLoopRunHandledSource: Int { get }

    Objective-C

    enum { kCFRunLoopRunFinished = 1, kCFRunLoopRunStopped = 2, kCFRunLoopRunTimedOut = 3, kCFRunLoopRunHandledSource = 4 };

    Constants

    • kCFRunLoopRunFinished

      kCFRunLoopRunFinished

      The running run loop mode has no sources or timers to process.

      Available in OS X v10.0 and later.

    • kCFRunLoopRunStopped

      kCFRunLoopRunStopped

      CFRunLoopStop was called on the run loop.

      Available in OS X v10.0 and later.

    • kCFRunLoopRunTimedOut

      kCFRunLoopRunTimedOut

      The specified time interval for running the run loop has passed.

      Available in OS X v10.0 and later.

    • kCFRunLoopRunHandledSource

      kCFRunLoopRunHandledSource

      A 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 OS X v10.0 and later.

    Import Statement

  • A run loop pseudo-mode that manages objects monitored in the “common” modes.

    Declaration

    Swift

    let kCFRunLoopCommonModes: CFString!

    Objective-C

    const CFStringRef kCFRunLoopCommonModes;

    Constants

    • kCFRunLoopCommonModes

      kCFRunLoopCommonModes

      Objects 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 OS X v10.0 and later.

    Discussion

    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.

    Import Statement

  • Default run loop mode.

    Declaration

    Swift

    let kCFRunLoopDefaultMode: CFString!

    Objective-C

    const CFStringRef kCFRunLoopDefaultMode;

    Constants

    • kCFRunLoopDefaultMode

      kCFRunLoopDefaultMode

      Run 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 OS X v10.0 and later.

    Import Statement