CFRunLoop.h

   1 /*
   2  * Copyright (c) 2014 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*      CFRunLoop.h
  25         Copyright (c) 1998-2014, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFRUNLOOP__)
  29 #define __COREFOUNDATION_CFRUNLOOP__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFArray.h>
  33 #include <CoreFoundation/CFDate.h>
  34 #include <CoreFoundation/CFString.h>
  35 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) || (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)
  36 #include <mach/port.h>
  37 #endif
  38
  39 CF_IMPLICIT_BRIDGING_ENABLED
  40 CF_EXTERN_C_BEGIN
  41
  42 typedef struct __CFRunLoop * CFRunLoopRef;
  43
  44 typedef struct __CFRunLoopSource * CFRunLoopSourceRef;
  45
  46 typedef struct __CFRunLoopObserver * CFRunLoopObserverRef;
  47
  48 typedef struct CF_BRIDGED_MUTABLE_TYPE(NSTimer) __CFRunLoopTimer * CFRunLoopTimerRef;
  49
  50 /* Reasons for CFRunLoopRunInMode() to Return */
  51 enum {
  52     kCFRunLoopRunFinished = 1,
  53     kCFRunLoopRunStopped = 2,
  54     kCFRunLoopRunTimedOut = 3,
  55     kCFRunLoopRunHandledSource = 4
  56 };
  57
  58 /* Run Loop Observer Activities */
  59 typedef CF_OPTIONS(CFOptionFlags, CFRunLoopActivity) {
  60     kCFRunLoopEntry = (1UL << 0),
  61     kCFRunLoopBeforeTimers = (1UL << 1),
  62     kCFRunLoopBeforeSources = (1UL << 2),
  63     kCFRunLoopBeforeWaiting = (1UL << 5),
  64     kCFRunLoopAfterWaiting = (1UL << 6),
  65     kCFRunLoopExit = (1UL << 7),
  66     kCFRunLoopAllActivities = 0x0FFFFFFFU
  67 };
  68
  69 CF_EXPORT const CFStringRef kCFRunLoopDefaultMode;
  70 CF_EXPORT const CFStringRef kCFRunLoopCommonModes;
  71
  72 CF_EXPORT CFTypeID CFRunLoopGetTypeID(void);
  73
  74 CF_EXPORT CFRunLoopRef CFRunLoopGetCurrent(void);
  75 CF_EXPORT CFRunLoopRef CFRunLoopGetMain(void);
  76
  77 CF_EXPORT CFStringRef CFRunLoopCopyCurrentMode(CFRunLoopRef rl);
  78
  79 CF_EXPORT CFArrayRef CFRunLoopCopyAllModes(CFRunLoopRef rl);
  80
  81 CF_EXPORT void CFRunLoopAddCommonMode(CFRunLoopRef rl, CFStringRef mode);
  82
  83 CF_EXPORT CFAbsoluteTime CFRunLoopGetNextTimerFireDate(CFRunLoopRef rl, CFStringRef mode);
  84
  85 CF_EXPORT void CFRunLoopRun(void);
  86 CF_EXPORT SInt32 CFRunLoopRunInMode(CFStringRef mode, CFTimeInterval seconds, Boolean returnAfterSourceHandled);
  87 CF_EXPORT Boolean CFRunLoopIsWaiting(CFRunLoopRef rl);
  88 CF_EXPORT void CFRunLoopWakeUp(CFRunLoopRef rl);
  89 CF_EXPORT void CFRunLoopStop(CFRunLoopRef rl);
  90
  91 #if __BLOCKS__
  92 CF_EXPORT void CFRunLoopPerformBlock(CFRunLoopRef rl, CFTypeRef mode, void (^block)(void)) CF_AVAILABLE(10_6, 4_0);
  93 #endif
  94
  95 CF_EXPORT Boolean CFRunLoopContainsSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
  96 CF_EXPORT void CFRunLoopAddSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
  97 CF_EXPORT void CFRunLoopRemoveSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
  98
  99 CF_EXPORT Boolean CFRunLoopContainsObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
 100 CF_EXPORT void CFRunLoopAddObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
 101 CF_EXPORT void CFRunLoopRemoveObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
 102
 103 CF_EXPORT Boolean CFRunLoopContainsTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
 104 CF_EXPORT void CFRunLoopAddTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
 105 CF_EXPORT void CFRunLoopRemoveTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
 106
 107 typedef struct {
 108     CFIndex     version;
 109     void *      info;
 110     const void *(*retain)(const void *info);
 111     void        (*release)(const void *info);
 112     CFStringRef (*copyDescription)(const void *info);
 113     Boolean     (*equal)(const void *info1, const void *info2);
 114     CFHashCode  (*hash)(const void *info);
 115     void        (*schedule)(void *info, CFRunLoopRef rl, CFStringRef mode);
 116     void        (*cancel)(void *info, CFRunLoopRef rl, CFStringRef mode);
 117     void        (*perform)(void *info);
 118 } CFRunLoopSourceContext;
 119
 120 typedef struct {
 121     CFIndex     version;
 122     void *      info;
 123     const void *(*retain)(const void *info);
 124     void        (*release)(const void *info);
 125     CFStringRef (*copyDescription)(const void *info);
 126     Boolean     (*equal)(const void *info1, const void *info2);
 127     CFHashCode  (*hash)(const void *info);
 128 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) || (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)
 129     mach_port_t (*getPort)(void *info);
 130     void *      (*perform)(void *msg, CFIndex size, CFAllocatorRef allocator, void *info);
 131 #else
 132     void *      (*getPort)(void *info);
 133     void        (*perform)(void *info);
 134 #endif
 135 } CFRunLoopSourceContext1;
 136
 137 CF_EXPORT CFTypeID CFRunLoopSourceGetTypeID(void);
 138
 139 CF_EXPORT CFRunLoopSourceRef CFRunLoopSourceCreate(CFAllocatorRef allocator, CFIndex order, CFRunLoopSourceContext *context);
 140
 141 CF_EXPORT CFIndex CFRunLoopSourceGetOrder(CFRunLoopSourceRef source);
 142 CF_EXPORT void CFRunLoopSourceInvalidate(CFRunLoopSourceRef source);
 143 CF_EXPORT Boolean CFRunLoopSourceIsValid(CFRunLoopSourceRef source);
 144 CF_EXPORT void CFRunLoopSourceGetContext(CFRunLoopSourceRef source, CFRunLoopSourceContext *context);
 145 CF_EXPORT void CFRunLoopSourceSignal(CFRunLoopSourceRef source);
 146
 147 typedef struct {
 148     CFIndex     version;
 149     void *      info;
 150     const void *(*retain)(const void *info);
 151     void        (*release)(const void *info);
 152     CFStringRef (*copyDescription)(const void *info);
 153 } CFRunLoopObserverContext;
 154
 155 typedef void (*CFRunLoopObserverCallBack)(CFRunLoopObserverRef observer, CFRunLoopActivity activity, void *info);
 156
 157 CF_EXPORT CFTypeID CFRunLoopObserverGetTypeID(void);
 158
 159 CF_EXPORT CFRunLoopObserverRef CFRunLoopObserverCreate(CFAllocatorRef allocator, CFOptionFlags activities, Boolean repeats, CFIndex order, CFRunLoopObserverCallBack callout, CFRunLoopObserverContext *context);
 160 #if __BLOCKS__
 161 CF_EXPORT CFRunLoopObserverRef CFRunLoopObserverCreateWithHandler(CFAllocatorRef allocator, CFOptionFlags activities, Boolean repeats, CFIndex order, void (^block) (CFRunLoopObserverRef observer, CFRunLoopActivity activity)) CF_AVAILABLE(10_7, 5_0);
 162 #endif
 163
 164 CF_EXPORT CFOptionFlags CFRunLoopObserverGetActivities(CFRunLoopObserverRef observer);
 165 CF_EXPORT Boolean CFRunLoopObserverDoesRepeat(CFRunLoopObserverRef observer);
 166 CF_EXPORT CFIndex CFRunLoopObserverGetOrder(CFRunLoopObserverRef observer);
 167 CF_EXPORT void CFRunLoopObserverInvalidate(CFRunLoopObserverRef observer);
 168 CF_EXPORT Boolean CFRunLoopObserverIsValid(CFRunLoopObserverRef observer);
 169 CF_EXPORT void CFRunLoopObserverGetContext(CFRunLoopObserverRef observer, CFRunLoopObserverContext *context);
 170
 171 typedef struct {
 172     CFIndex     version;
 173     void *      info;
 174     const void *(*retain)(const void *info);
 175     void        (*release)(const void *info);
 176     CFStringRef (*copyDescription)(const void *info);
 177 } CFRunLoopTimerContext;
 178
 179 typedef void (*CFRunLoopTimerCallBack)(CFRunLoopTimerRef timer, void *info);
 180
 181 CF_EXPORT CFTypeID CFRunLoopTimerGetTypeID(void);
 182
 183 CF_EXPORT CFRunLoopTimerRef CFRunLoopTimerCreate(CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, CFRunLoopTimerCallBack callout, CFRunLoopTimerContext *context);
 184 #if __BLOCKS__
 185 CF_EXPORT CFRunLoopTimerRef CFRunLoopTimerCreateWithHandler(CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, void (^block) (CFRunLoopTimerRef timer)) CF_AVAILABLE(10_7, 5_0);
 186 #endif
 187
 188 CF_EXPORT CFAbsoluteTime CFRunLoopTimerGetNextFireDate(CFRunLoopTimerRef timer);
 189 CF_EXPORT void CFRunLoopTimerSetNextFireDate(CFRunLoopTimerRef timer, CFAbsoluteTime fireDate);
 190 CF_EXPORT CFTimeInterval CFRunLoopTimerGetInterval(CFRunLoopTimerRef timer);
 191 CF_EXPORT Boolean CFRunLoopTimerDoesRepeat(CFRunLoopTimerRef timer);
 192 CF_EXPORT CFIndex CFRunLoopTimerGetOrder(CFRunLoopTimerRef timer);
 193 CF_EXPORT void CFRunLoopTimerInvalidate(CFRunLoopTimerRef timer);
 194 CF_EXPORT Boolean CFRunLoopTimerIsValid(CFRunLoopTimerRef timer);
 195 CF_EXPORT void CFRunLoopTimerGetContext(CFRunLoopTimerRef timer, CFRunLoopTimerContext *context);
 196
 197 // Setting a tolerance for a timer allows it to fire later than the scheduled fire date, improving the ability of the system to optimize for increased power savings and responsiveness. The timer may fire at any time between its scheduled fire date and the scheduled fire date plus the tolerance. The timer will not fire before the scheduled fire date. For repeating timers, the next fire date is calculated from the original fire date regardless of tolerance applied at individual fire times, to avoid drift. The default value is zero, which means no additional tolerance is applied. The system reserves the right to apply a small amount of tolerance to certain timers regardless of the value of this property.
 198 // As the user of the timer, you will have the best idea of what an appropriate tolerance for a timer may be. A general rule of thumb, though, is to set the tolerance to at least 10% of the interval, for a repeating timer. Even a small amount of tolerance will have a significant positive impact on the power usage of your application. The system may put a maximum value of the tolerance.
 199 CF_EXPORT CFTimeInterval CFRunLoopTimerGetTolerance(CFRunLoopTimerRef timer) CF_AVAILABLE(10_9, 7_0);
 200 CF_EXPORT void CFRunLoopTimerSetTolerance(CFRunLoopTimerRef timer, CFTimeInterval tolerance) CF_AVAILABLE(10_9, 7_0);
 201
 202 CF_EXTERN_C_END
 203 CF_IMPLICIT_BRIDGING_DISABLED
 204
 205 #endif /* ! __COREFOUNDATION_CFRUNLOOP__ */
 206