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-2013, 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
39CF_EXTERN_C_BEGIN
40
41typedef struct __CFRunLoop * CFRunLoopRef;
42
43typedef struct __CFRunLoopSource * CFRunLoopSourceRef;
44
45typedef struct __CFRunLoopObserver * CFRunLoopObserverRef;
46
47typedef struct __CFRunLoopTimer * CFRunLoopTimerRef;
48
49/* Reasons for CFRunLoopRunInMode() to Return */
50enum {
51    kCFRunLoopRunFinished = 1,
52    kCFRunLoopRunStopped = 2,
53    kCFRunLoopRunTimedOut = 3,
54    kCFRunLoopRunHandledSource = 4
55};
56
57/* Run Loop Observer Activities */
58typedef CF_OPTIONS(CFOptionFlags, CFRunLoopActivity) {
59    kCFRunLoopEntry = (1UL << 0),
60    kCFRunLoopBeforeTimers = (1UL << 1),
61    kCFRunLoopBeforeSources = (1UL << 2),
62    kCFRunLoopBeforeWaiting = (1UL << 5),
63    kCFRunLoopAfterWaiting = (1UL << 6),
64    kCFRunLoopExit = (1UL << 7),
65    kCFRunLoopAllActivities = 0x0FFFFFFFU
66};
67
68CF_EXPORT const CFStringRef kCFRunLoopDefaultMode;
69CF_EXPORT const CFStringRef kCFRunLoopCommonModes;
70
71CF_EXPORT CFTypeID CFRunLoopGetTypeID(void);
72
73CF_EXPORT CFRunLoopRef CFRunLoopGetCurrent(void);
74CF_EXPORT CFRunLoopRef CFRunLoopGetMain(void);
75
76CF_EXPORT CFStringRef CFRunLoopCopyCurrentMode(CFRunLoopRef rl);
77
78CF_EXPORT CFArrayRef CFRunLoopCopyAllModes(CFRunLoopRef rl);
79
80CF_EXPORT void CFRunLoopAddCommonMode(CFRunLoopRef rl, CFStringRef mode);
81
82CF_EXPORT CFAbsoluteTime CFRunLoopGetNextTimerFireDate(CFRunLoopRef rl, CFStringRef mode);
83
84CF_EXPORT void CFRunLoopRun(void);
85CF_EXPORT SInt32 CFRunLoopRunInMode(CFStringRef mode, CFTimeInterval seconds, Boolean returnAfterSourceHandled);
86CF_EXPORT Boolean CFRunLoopIsWaiting(CFRunLoopRef rl);
87CF_EXPORT void CFRunLoopWakeUp(CFRunLoopRef rl);
88CF_EXPORT void CFRunLoopStop(CFRunLoopRef rl);
89
90#if __BLOCKS__
91CF_EXPORT void CFRunLoopPerformBlock(CFRunLoopRef rl, CFTypeRef mode, void (^block)(void)) CF_AVAILABLE(10_6, 4_0);
92#endif
93
94CF_EXPORT Boolean CFRunLoopContainsSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
95CF_EXPORT void CFRunLoopAddSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
96CF_EXPORT void CFRunLoopRemoveSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
97
98CF_EXPORT Boolean CFRunLoopContainsObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
99CF_EXPORT void CFRunLoopAddObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
100CF_EXPORT void CFRunLoopRemoveObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
101
102CF_EXPORT Boolean CFRunLoopContainsTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
103CF_EXPORT void CFRunLoopAddTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
104CF_EXPORT void CFRunLoopRemoveTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
105
106typedef struct {
107    CFIndex	version;
108    void *	info;
109    const void *(*retain)(const void *info);
110    void	(*release)(const void *info);
111    CFStringRef	(*copyDescription)(const void *info);
112    Boolean	(*equal)(const void *info1, const void *info2);
113    CFHashCode	(*hash)(const void *info);
114    void	(*schedule)(void *info, CFRunLoopRef rl, CFStringRef mode);
115    void	(*cancel)(void *info, CFRunLoopRef rl, CFStringRef mode);
116    void	(*perform)(void *info);
117} CFRunLoopSourceContext;
118
119typedef struct {
120    CFIndex	version;
121    void *	info;
122    const void *(*retain)(const void *info);
123    void	(*release)(const void *info);
124    CFStringRef	(*copyDescription)(const void *info);
125    Boolean	(*equal)(const void *info1, const void *info2);
126    CFHashCode	(*hash)(const void *info);
127#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) || (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)
128    mach_port_t	(*getPort)(void *info);
129    void *	(*perform)(void *msg, CFIndex size, CFAllocatorRef allocator, void *info);
130#else
131    void *	(*getPort)(void *info);
132    void	(*perform)(void *info);
133#endif
134} CFRunLoopSourceContext1;
135
136CF_EXPORT CFTypeID CFRunLoopSourceGetTypeID(void);
137
138CF_EXPORT CFRunLoopSourceRef CFRunLoopSourceCreate(CFAllocatorRef allocator, CFIndex order, CFRunLoopSourceContext *context);
139
140CF_EXPORT CFIndex CFRunLoopSourceGetOrder(CFRunLoopSourceRef source);
141CF_EXPORT void CFRunLoopSourceInvalidate(CFRunLoopSourceRef source);
142CF_EXPORT Boolean CFRunLoopSourceIsValid(CFRunLoopSourceRef source);
143CF_EXPORT void CFRunLoopSourceGetContext(CFRunLoopSourceRef source, CFRunLoopSourceContext *context);
144CF_EXPORT void CFRunLoopSourceSignal(CFRunLoopSourceRef source);
145
146typedef struct {
147    CFIndex	version;
148    void *	info;
149    const void *(*retain)(const void *info);
150    void	(*release)(const void *info);
151    CFStringRef	(*copyDescription)(const void *info);
152} CFRunLoopObserverContext;
153
154typedef void (*CFRunLoopObserverCallBack)(CFRunLoopObserverRef observer, CFRunLoopActivity activity, void *info);
155
156CF_EXPORT CFTypeID CFRunLoopObserverGetTypeID(void);
157
158CF_EXPORT CFRunLoopObserverRef CFRunLoopObserverCreate(CFAllocatorRef allocator, CFOptionFlags activities, Boolean repeats, CFIndex order, CFRunLoopObserverCallBack callout, CFRunLoopObserverContext *context);
159#if __BLOCKS__
160CF_EXPORT CFRunLoopObserverRef CFRunLoopObserverCreateWithHandler(CFAllocatorRef allocator, CFOptionFlags activities, Boolean repeats, CFIndex order, void (^block) (CFRunLoopObserverRef observer, CFRunLoopActivity activity)) CF_AVAILABLE(10_7, 5_0);
161#endif
162
163CF_EXPORT CFOptionFlags CFRunLoopObserverGetActivities(CFRunLoopObserverRef observer);
164CF_EXPORT Boolean CFRunLoopObserverDoesRepeat(CFRunLoopObserverRef observer);
165CF_EXPORT CFIndex CFRunLoopObserverGetOrder(CFRunLoopObserverRef observer);
166CF_EXPORT void CFRunLoopObserverInvalidate(CFRunLoopObserverRef observer);
167CF_EXPORT Boolean CFRunLoopObserverIsValid(CFRunLoopObserverRef observer);
168CF_EXPORT void CFRunLoopObserverGetContext(CFRunLoopObserverRef observer, CFRunLoopObserverContext *context);
169
170typedef struct {
171    CFIndex	version;
172    void *	info;
173    const void *(*retain)(const void *info);
174    void	(*release)(const void *info);
175    CFStringRef	(*copyDescription)(const void *info);
176} CFRunLoopTimerContext;
177
178typedef void (*CFRunLoopTimerCallBack)(CFRunLoopTimerRef timer, void *info);
179
180CF_EXPORT CFTypeID CFRunLoopTimerGetTypeID(void);
181
182CF_EXPORT CFRunLoopTimerRef CFRunLoopTimerCreate(CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, CFRunLoopTimerCallBack callout, CFRunLoopTimerContext *context);
183#if __BLOCKS__
184CF_EXPORT CFRunLoopTimerRef CFRunLoopTimerCreateWithHandler(CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, void (^block) (CFRunLoopTimerRef timer)) CF_AVAILABLE(10_7, 5_0);
185#endif
186
187CF_EXPORT CFAbsoluteTime CFRunLoopTimerGetNextFireDate(CFRunLoopTimerRef timer);
188CF_EXPORT void CFRunLoopTimerSetNextFireDate(CFRunLoopTimerRef timer, CFAbsoluteTime fireDate);
189CF_EXPORT CFTimeInterval CFRunLoopTimerGetInterval(CFRunLoopTimerRef timer);
190CF_EXPORT Boolean CFRunLoopTimerDoesRepeat(CFRunLoopTimerRef timer);
191CF_EXPORT CFIndex CFRunLoopTimerGetOrder(CFRunLoopTimerRef timer);
192CF_EXPORT void CFRunLoopTimerInvalidate(CFRunLoopTimerRef timer);
193CF_EXPORT Boolean CFRunLoopTimerIsValid(CFRunLoopTimerRef timer);
194CF_EXPORT void CFRunLoopTimerGetContext(CFRunLoopTimerRef timer, CFRunLoopTimerContext *context);
195
196// 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.
197// 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.
198CF_EXPORT CFTimeInterval CFRunLoopTimerGetTolerance(CFRunLoopTimerRef timer) CF_AVAILABLE(10_9, 7_0);
199CF_EXPORT void CFRunLoopTimerSetTolerance(CFRunLoopTimerRef timer, CFTimeInterval tolerance) CF_AVAILABLE(10_9, 7_0);
200
201CF_EXTERN_C_END
202
203#endif /* ! __COREFOUNDATION_CFRUNLOOP__ */
204
205