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