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)
44DISPATCH_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)
69DISPATCH_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)
79DISPATCH_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")
90DISPATCH_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)
100DISPATCH_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)
108__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
109DISPATCH_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 */
150enum {
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 */
200enum {
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 */
226enum {
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 */
243enum {
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 */
254enum {
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
266enum {
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
286enum {
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 */
305DISPATCH_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)
324DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
325DISPATCH_NOTHROW
326dispatch_timer_aggregate_t
327dispatch_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)
346DISPATCH_EXPORT DISPATCH_NOTHROW
347uint64_t
348dispatch_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 */
358typedef 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)
362DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
363mach_msg_return_t
364dispatch_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)
374DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NONNULL_ALL
375DISPATCH_NOTHROW
376void *
377dispatch_mach_msg_get_context(mach_msg_header_t *msg);
378#endif
379
380__END_DECLS
381
382#endif
383