1 /*
2 * Copyright (c) 2008-2013 Apple Inc. All rights reserved.
3 *
4 * @APPLE_APACHE_LICENSE_HEADER_START@
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 *
18 * @APPLE_APACHE_LICENSE_HEADER_END@
19 */
20
21 /*
22 * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
23 * which are subject to change in future releases of Mac OS X. Any applications
24 * relying on these interfaces WILL break.
25 */
26
27 #ifndef __DISPATCH_SOURCE_PRIVATE__
28 #define __DISPATCH_SOURCE_PRIVATE__
29
30 #ifndef __DISPATCH_INDIRECT__
31 #error "Please #include <dispatch/private.h> instead of this file directly."
32 #include <dispatch/base.h> // for HeaderDoc
33 #endif
34
35 /*!
36 * @const DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE
37 * @discussion A dispatch timer source that is part of a timer aggregate.
38 * The handle is the dispatch timer aggregate object.
39 * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
40 */
41 #define DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE \
42 (&_dispatch_source_type_timer_with_aggregate)
43 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
44 DISPATCH_SOURCE_TYPE_DECL(timer_with_aggregate);
45
46 /*!
47 * @const DISPATCH_SOURCE_TYPE_INTERVAL
48 * @discussion A dispatch source that submits the event handler block at a
49 * specified time interval, phase-aligned with all other interval sources on
50 * the system that have the same interval value.
51 *
52 * The initial submission of the event handler will occur at some point during
53 * the first time interval after the source is created (assuming the source is
54 * resumed at that time).
55 *
56 * By default, the unit for the interval value is milliseconds and the leeway
57 * (maximum amount of time any individual handler submission may be deferred to
58 * align with other system activity) for the source is fixed at interval/2.
59 *
60 * If the DISPATCH_INTERVAL_UI_ANIMATION flag is specified, the unit for the
61 * interval value is animation frames (1/60th of a second) and the leeway is
62 * fixed at one frame.
63 *
64 * The handle is the interval value in milliseconds or frames.
65 * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
66 */
67 #define DISPATCH_SOURCE_TYPE_INTERVAL (&_dispatch_source_type_interval)
68 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
69 DISPATCH_SOURCE_TYPE_DECL(interval);
70
71 /*!
72 * @const DISPATCH_SOURCE_TYPE_VFS
73 * @discussion Apple-internal dispatch source that monitors for vfs events
74 * defined by dispatch_vfs_flags_t.
75 * The handle is a process identifier (pid_t).
76 */
77 #define DISPATCH_SOURCE_TYPE_VFS (&_dispatch_source_type_vfs)
78 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
79 DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vfs;
80
81 /*!
82 * @const DISPATCH_SOURCE_TYPE_VM
83 * @discussion A dispatch source that monitors virtual memory
84 * The mask is a mask of desired events from dispatch_source_vm_flags_t.
85 * This type is deprecated, use DISPATCH_SOURCE_TYPE_MEMORYSTATUS instead.
86 */
87 #define DISPATCH_SOURCE_TYPE_VM (&_dispatch_source_type_vm)
88 __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_7, __MAC_10_10, __IPHONE_4_3,
89 __IPHONE_8_0, "Use DISPATCH_SOURCE_TYPE_MEMORYSTATUS instead")
90 DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vm;
91
92 /*!
93 * @const DISPATCH_SOURCE_TYPE_MEMORYSTATUS
94 * @discussion A dispatch source that monitors memory status
95 * The mask is a mask of desired events from
96 * dispatch_source_memorystatus_flags_t.
97 */
98 #define DISPATCH_SOURCE_TYPE_MEMORYSTATUS (&_dispatch_source_type_memorystatus)
99 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
100 DISPATCH_EXPORT const struct dispatch_source_type_s
101 _dispatch_source_type_memorystatus;
102
103 /*!
104 * @const DISPATCH_SOURCE_TYPE_SOCK
105 * @discussion A dispatch source that monitors events on socket state changes.
106 */
107 #define DISPATCH_SOURCE_TYPE_SOCK (&_dispatch_source_type_sock)
__OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_6_0)108 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
109 DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_sock;
110
111 /*!
112 * @enum dispatch_source_sock_flags_t
113 *
114 * @constant DISPATCH_SOCK_CONNRESET
115 * Received RST
116 *
117 * @constant DISPATCH_SOCK_READCLOSED
118 * Read side is shutdown
119 *
120 * @constant DISPATCH_SOCK_WRITECLOSED
121 * Write side is shutdown
122 *
123 * @constant DISPATCH_SOCK_TIMEOUT
124 * Timeout: rexmt, keep-alive or persist
125 *
126 * @constant DISPATCH_SOCK_NOSRCADDR
127 * Source address not available
128 *
129 * @constant DISPATCH_SOCK_IFDENIED
130 * Interface denied connection
131 *
132 * @constant DISPATCH_SOCK_SUSPEND
133 * Output queue suspended
134 *
135 * @constant DISPATCH_SOCK_RESUME
136 * Output queue resumed
137 *
138 * @constant DISPATCH_SOCK_KEEPALIVE
139 * TCP Keepalive received
140 *
141 * @constant DISPATCH_SOCK_CONNECTED
142 * Socket is connected
143 *
144 * @constant DISPATCH_SOCK_DISCONNECTED
145 * Socket is disconnected
146 *
147 * @constant DISPATCH_SOCK_CONNINFO_UPDATED
148 * Connection info was updated
149 */
150 enum {
151 DISPATCH_SOCK_CONNRESET = 0x00000001,
152 DISPATCH_SOCK_READCLOSED = 0x00000002,
153 DISPATCH_SOCK_WRITECLOSED = 0x00000004,
154 DISPATCH_SOCK_TIMEOUT = 0x00000008,
155 DISPATCH_SOCK_NOSRCADDR = 0x00000010,
156 DISPATCH_SOCK_IFDENIED = 0x00000020,
157 DISPATCH_SOCK_SUSPEND = 0x00000040,
158 DISPATCH_SOCK_RESUME = 0x00000080,
159 DISPATCH_SOCK_KEEPALIVE = 0x00000100,
160 DISPATCH_SOCK_ADAPTIVE_WTIMO = 0x00000200,
161 DISPATCH_SOCK_ADAPTIVE_RTIMO = 0x00000400,
162 DISPATCH_SOCK_CONNECTED = 0x00000800,
163 DISPATCH_SOCK_DISCONNECTED = 0x00001000,
164 DISPATCH_SOCK_CONNINFO_UPDATED = 0x00002000,
165 };
166
167 /*!
168 * @enum dispatch_source_vfs_flags_t
169 *
170 * @constant DISPATCH_VFS_NOTRESP
171 * Server down.
172 *
173 * @constant DISPATCH_VFS_NEEDAUTH
174 * Server bad auth.
175 *
176 * @constant DISPATCH_VFS_LOWDISK
177 * We're low on space.
178 *
179 * @constant DISPATCH_VFS_MOUNT
180 * New filesystem arrived.
181 *
182 * @constant DISPATCH_VFS_UNMOUNT
183 * Filesystem has left.
184 *
185 * @constant DISPATCH_VFS_DEAD
186 * Filesystem is dead, needs force unmount.
187 *
188 * @constant DISPATCH_VFS_ASSIST
189 * Filesystem needs assistance from external program.
190 *
191 * @constant DISPATCH_VFS_NOTRESPLOCK
192 * Server lockd down.
193 *
194 * @constant DISPATCH_VFS_UPDATE
195 * Filesystem information has changed.
196 *
197 * @constant DISPATCH_VFS_VERYLOWDISK
198 * File system has *very* little disk space left.
199 */
200 enum {
201 DISPATCH_VFS_NOTRESP = 0x0001,
202 DISPATCH_VFS_NEEDAUTH = 0x0002,
203 DISPATCH_VFS_LOWDISK = 0x0004,
204 DISPATCH_VFS_MOUNT = 0x0008,
205 DISPATCH_VFS_UNMOUNT = 0x0010,
206 DISPATCH_VFS_DEAD = 0x0020,
207 DISPATCH_VFS_ASSIST = 0x0040,
208 DISPATCH_VFS_NOTRESPLOCK = 0x0080,
209 DISPATCH_VFS_UPDATE = 0x0100,
210 DISPATCH_VFS_VERYLOWDISK = 0x0200,
211 };
212
213 /*!
214 * @enum dispatch_source_timer_flags_t
215 *
216 * @constant DISPATCH_TIMER_BACKGROUND
217 * Specifies that the timer is used to trigger low priority maintenance-level
218 * activity and that the system may apply larger minimum leeway values to the
219 * timer in order to align it with other system activity.
220 *
221 * @constant DISPATCH_INTERVAL_UI_ANIMATION
222 * Specifies that the interval source is used for UI animation. The unit for
223 * the interval value of such sources is frames (1/60th of a second) and the
224 * leeway is fixed at one frame.
225 */
226 enum {
227 DISPATCH_TIMER_BACKGROUND = 0x2,
228 DISPATCH_INTERVAL_UI_ANIMATION = 0x20,
229 };
230
231 /*!
232 * @enum dispatch_source_mach_send_flags_t
233 *
234 * @constant DISPATCH_MACH_SEND_POSSIBLE
235 * The mach port corresponding to the given send right has space available
236 * for messages. Delivered only once a mach_msg() to that send right with
237 * options MACH_SEND_MSG|MACH_SEND_TIMEOUT|MACH_SEND_NOTIFY has returned
238 * MACH_SEND_TIMED_OUT (and not again until the next such mach_msg() timeout).
239 * NOTE: The source must have registered the send right for monitoring with the
240 * system for such a mach_msg() to arm the send-possible notifcation, so
241 * the initial send attempt must occur from a source registration handler.
242 */
243 enum {
244 DISPATCH_MACH_SEND_POSSIBLE = 0x8,
245 };
246
247 /*!
248 * @enum dispatch_source_proc_flags_t
249 *
250 * @constant DISPATCH_PROC_REAP
251 * The process has been reaped by the parent process via wait*().
252 * This flag is deprecated and will be removed in a future release.
253 */
254 enum {
255 DISPATCH_PROC_REAP __OSX_AVAILABLE_BUT_DEPRECATED(
256 __MAC_10_6, __MAC_10_9, __IPHONE_4_0, __IPHONE_7_0) = 0x10000000,
257 };
258
259 /*!
260 * @enum dispatch_source_vm_flags_t
261 *
262 * @constant DISPATCH_VM_PRESSURE
263 * The VM has experienced memory pressure.
264 */
265
266 enum {
267 DISPATCH_VM_PRESSURE __OSX_AVAILABLE_BUT_DEPRECATED_MSG(
268 __MAC_10_7, __MAC_10_10, __IPHONE_4_3, __IPHONE_8_0,
269 "Use DISPATCH_MEMORYSTATUS_PRESSURE_WARN instead") = 0x80000000,
270 };
271
272 /*!
273 * @enum dispatch_source_memorystatus_flags_t
274 *
275 * @constant DISPATCH_MEMORYSTATUS_PRESSURE_NORMAL
276 * The system's memory pressure state has returned to normal.
277 * @constant DISPATCH_MEMORYSTATUS_PRESSURE_WARN
278 * The system's memory pressure state has changed to warning.
279 * @constant DISPATCH_MEMORYSTATUS_PRESSURE_CRITICAL
280 * The system's memory pressure state has changed to critical.
281 * @constant DISPATCH_MEMORYSTATUS_LOW_SWAP
282 * The system's memory pressure state has entered the "low swap" condition.
283 * Restricted to the root user.
284 */
285
286 enum {
287 DISPATCH_MEMORYSTATUS_PRESSURE_NORMAL
288 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0) = 0x01,
289 DISPATCH_MEMORYSTATUS_PRESSURE_WARN
290 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0) = 0x02,
291 DISPATCH_MEMORYSTATUS_PRESSURE_CRITICAL
292 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_8_0) = 0x04,
293 DISPATCH_MEMORYSTATUS_LOW_SWAP
294 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x08,
295 };
296
297 __BEGIN_DECLS
298
299 /*!
300 * @typedef dispatch_timer_aggregate_t
301 *
302 * @abstract
303 * Dispatch timer aggregates are sets of related timers.
304 */
305 DISPATCH_DECL(dispatch_timer_aggregate);
306
307 /*!
308 * @function dispatch_timer_aggregate_create
309 *
310 * @abstract
311 * Creates a new dispatch timer aggregate.
312 *
313 * @discussion
314 * A dispatch timer aggregate is a set of related timers whose overall timing
315 * parameters can be queried.
316 *
317 * Timers are added to an aggregate when a timer source is created with type
318 * DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE.
319 *
320 * @result
321 * The newly created dispatch timer aggregate.
322 */
323 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
324 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
325 DISPATCH_NOTHROW
326 dispatch_timer_aggregate_t
327 dispatch_timer_aggregate_create(void);
328
329 /*!
330 * @function dispatch_timer_aggregate_get_delay
331 *
332 * @abstract
333 * Retrieves the delay until a timer in the given aggregate will next fire.
334 *
335 * @param aggregate
336 * The dispatch timer aggregate to query.
337 *
338 * @param leeway_ptr
339 * Optional pointer to a variable filled with the leeway (in ns) that will be
340 * applied to the return value. May be NULL.
341 *
342 * @result
343 * Delay in ns from now.
344 */
345 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
346 DISPATCH_EXPORT DISPATCH_NOTHROW
347 uint64_t
348 dispatch_timer_aggregate_get_delay(dispatch_timer_aggregate_t aggregate,
349 uint64_t *leeway_ptr);
350
351 #if TARGET_OS_MAC
352 /*!
353 * @typedef dispatch_mig_callback_t
354 *
355 * @abstract
356 * The signature of a function that handles Mach message delivery and response.
357 */
358 typedef boolean_t (*dispatch_mig_callback_t)(mach_msg_header_t *message,
359 mach_msg_header_t *reply);
360
361 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
362 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
363 mach_msg_return_t
364 dispatch_mig_server(dispatch_source_t ds, size_t maxmsgsz,
365 dispatch_mig_callback_t callback);
366
367 /*!
368 * @function dispatch_mach_msg_get_context
369 *
370 * @abstract
371 * Extract the context pointer from a mach message trailer.
372 */
373 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
374 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NONNULL_ALL
375 DISPATCH_NOTHROW
376 void *
377 dispatch_mach_msg_get_context(mach_msg_header_t *msg);
378 #endif
379
380 __END_DECLS
381
382 #endif
383