<!--
{
  "availability" : [
    "iOS: -",
    "iPadOS: -",
    "macCatalyst: -",
    "macOS: -",
    "tvOS: -",
    "visionOS: -",
    "watchOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "CoreFoundation",
  "identifier" : "/documentation/CoreFoundation/CFRunLoop",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Core Foundation"
    ],
    "preciseIdentifier" : "c:@T@CFRunLoopRef"
  },
  "title" : "CFRunLoop"
}
-->

# CFRunLoop

```
class CFRunLoop
```

## Overview

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`](/documentation/CoreFoundation/CFRunLoopSource)), timers ([`CFRunLoopTimer`](/documentation/CoreFoundation/CFRunLoopTimer)), and observers ([`CFRunLoopObserver`](/documentation/CoreFoundation/CFRunLoopObserver)). To receive callbacks when these objects need processing, you must first place these objects into a run loop with [`CFRunLoopAddSource(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopAddSource(_:_:_:)), [`CFRunLoopAddTimer(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopAddTimer(_:_:_:)), or [`CFRunLoopAddObserver(_:_:_:)`](/documentation/CoreFoundation/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 [`defaultMode`](/documentation/CoreFoundation/CFRunLoopMode/defaultMode) 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 [`commonModes`](/documentation/CoreFoundation/CFRunLoopMode/commonModes) constant for the mode when configuring the object. Each run loop has its own independent set of common modes and the default mode ([`defaultMode`](/documentation/CoreFoundation/CFRunLoopMode/defaultMode)) is always a member of the set. To add a mode to the set of common modes, use the [`CFRunLoopAddCommonMode(_:_:)`](/documentation/CoreFoundation/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()`](/documentation/CoreFoundation/CFRunLoopGetCurrent()). Call [`CFRunLoopRun()`](/documentation/CoreFoundation/CFRunLoopRun()) to run the current thread’s run loop in the default mode until the run loop is stopped with [`CFRunLoopStop(_:)`](/documentation/CoreFoundation/CFRunLoopStop(_:)). You can also call [`CFRunLoopRunInMode(_:_:_:)`](/documentation/CoreFoundation/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()`](/documentation/CoreFoundation/CFRunLoopRun()) or [`CFRunLoopRunInMode(_:_:_:)`](/documentation/CoreFoundation/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 <doc://com.apple.documentation/documentation/Foundation/RunLoop/getCFRunLoop()> method of <doc://com.apple.documentation/documentation/Foundation/RunLoop> to obtain the corresponding [`CFRunLoop`](/documentation/CoreFoundation/CFRunLoop) type. In Carbon applications, use the `GetCFRunLoopFromEventLoop` function.

For more information about how run loops behave, see [Run Loops](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Multithreading/RunLoopManagement/RunLoopManagement.html#//apple_ref/doc/uid/10000057i-CH16) in [Threading Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Multithreading/Introduction/Introduction.html#//apple_ref/doc/uid/10000057i).

## Topics

### Getting a Run Loop

[`CFRunLoopGetCurrent()`](/documentation/CoreFoundation/CFRunLoopGetCurrent())

Returns the CFRunLoop object for the current thread.

[`CFRunLoopGetMain()`](/documentation/CoreFoundation/CFRunLoopGetMain())

Returns the main CFRunLoop object.

### Starting and Stopping a Run Loop

[`CFRunLoopRun()`](/documentation/CoreFoundation/CFRunLoopRun())

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

[`CFRunLoopRunInMode(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopRunInMode(_:_:_:))

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

[`CFRunLoopWakeUp(_:)`](/documentation/CoreFoundation/CFRunLoopWakeUp(_:))

Wakes a waiting CFRunLoop object.

[`CFRunLoopStop(_:)`](/documentation/CoreFoundation/CFRunLoopStop(_:))

Forces a CFRunLoop object to stop running.

[`CFRunLoopIsWaiting(_:)`](/documentation/CoreFoundation/CFRunLoopIsWaiting(_:))

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

### Managing Sources

[`CFRunLoopAddSource(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopAddSource(_:_:_:))

Adds a CFRunLoopSource object to a run loop mode.

[`CFRunLoopContainsSource(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopContainsSource(_:_:_:))

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

[`CFRunLoopRemoveSource(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopRemoveSource(_:_:_:))

Removes a CFRunLoopSource object from a run loop mode.

### Managing Observers

[`CFRunLoopAddObserver(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopAddObserver(_:_:_:))

Adds a CFRunLoopObserver object to a run loop mode.

[`CFRunLoopContainsObserver(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopContainsObserver(_:_:_:))

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

[`CFRunLoopRemoveObserver(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopRemoveObserver(_:_:_:))

Removes a CFRunLoopObserver object from a run loop mode.

### Managing Run Loop Modes

[`CFRunLoopAddCommonMode(_:_:)`](/documentation/CoreFoundation/CFRunLoopAddCommonMode(_:_:))

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

[`CFRunLoopCopyAllModes(_:)`](/documentation/CoreFoundation/CFRunLoopCopyAllModes(_:))

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

[`CFRunLoopCopyCurrentMode(_:)`](/documentation/CoreFoundation/CFRunLoopCopyCurrentMode(_:))

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

### Managing Timers

[`CFRunLoopAddTimer(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopAddTimer(_:_:_:))

Adds a CFRunLoopTimer object to a run loop mode.

[`CFRunLoopGetNextTimerFireDate(_:_:)`](/documentation/CoreFoundation/CFRunLoopGetNextTimerFireDate(_:_:))

Returns the time at which the next timer will fire.

[`CFRunLoopRemoveTimer(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopRemoveTimer(_:_:_:))

Removes a CFRunLoopTimer object from a run loop mode.

[`CFRunLoopContainsTimer(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopContainsTimer(_:_:_:))

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

### Scheduling Blocks

[`CFRunLoopPerformBlock(_:_:_:)`](/documentation/CoreFoundation/CFRunLoopPerformBlock(_:_:_:))

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

### Getting the CFRunLoop Type ID

[`CFRunLoopGetTypeID()`](/documentation/CoreFoundation/CFRunLoopGetTypeID())

Returns the type identifier for the CFRunLoop opaque type.

### Constants

[CFRunLoopRunInMode Exit Codes](/documentation/CoreFoundation/cfrunloopruninmode_exit_codes)

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

[Common Mode Flag](/documentation/CoreFoundation/common-mode-flag)

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

[Default Run Loop Mode](/documentation/CoreFoundation/default-run-loop-mode)

Default run loop mode.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)