private/source_private.h

   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 DISPATCH_ASSUME_NONNULL_BEGIN
  36
  37 __BEGIN_DECLS
  38
  39 /*!
  40  * @const DISPATCH_SOURCE_TYPE_INTERVAL
  41  * @discussion A dispatch source that submits the event handler block at a
  42  * specified time interval, phase-aligned with all other interval sources on
  43  * the system that have the same interval value.
  44  *
  45  * The initial submission of the event handler will occur at some point during
  46  * the first time interval after the source is created (assuming the source is
  47  * resumed at that time).
  48  *
  49  * By default, the unit for the interval value is milliseconds and the leeway
  50  * (maximum amount of time any individual handler submission may be deferred to
  51  * align with other system activity) for the source is fixed at interval/2.
  52  *
  53  * If the DISPATCH_INTERVAL_UI_ANIMATION flag is specified, the unit for the
  54  * interval value is animation frames (1/60th of a second) and the leeway is
  55  * fixed at one frame.
  56  *
  57  * The handle is the interval value in milliseconds or frames.
  58  * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
  59  */
  60 #define DISPATCH_SOURCE_TYPE_INTERVAL (&_dispatch_source_type_interval)
  61 API_AVAILABLE(macos(10.9), ios(7.0))
  62 DISPATCH_SOURCE_TYPE_DECL(interval);
  63
  64 /*!
  65  * @const DISPATCH_SOURCE_TYPE_VFS
  66  * @discussion Apple-internal dispatch source that monitors for vfs events
  67  * defined by dispatch_vfs_flags_t.
  68  * The handle is a process identifier (pid_t).
  69  */
  70 #define DISPATCH_SOURCE_TYPE_VFS (&_dispatch_source_type_vfs)
  71 API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
  72 DISPATCH_SOURCE_TYPE_DECL(vfs);
  73
  74 /*!
  75  * @const DISPATCH_SOURCE_TYPE_VM
  76  * @discussion A dispatch source that monitors virtual memory
  77  * The mask is a mask of desired events from dispatch_source_vm_flags_t.
  78  * This type is deprecated, use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead.
  79  */
  80 #define DISPATCH_SOURCE_TYPE_VM (&_dispatch_source_type_vm)
  81 API_DEPRECATED_WITH_REPLACEMENT("DISPATCH_SOURCE_TYPE_MEMORYPRESSURE",
  82                 macos(10.7,10.10), ios(4.3,8.0)) DISPATCH_LINUX_UNAVAILABLE()
  83 DISPATCH_SOURCE_TYPE_DECL(vm);
  84
  85 /*!
  86  * @const DISPATCH_SOURCE_TYPE_MEMORYSTATUS
  87  * @discussion A dispatch source that monitors memory status
  88  * The mask is a mask of desired events from
  89  * dispatch_source_memorystatus_flags_t.
  90  */
  91 #define DISPATCH_SOURCE_TYPE_MEMORYSTATUS (&_dispatch_source_type_memorystatus)
  92 API_DEPRECATED_WITH_REPLACEMENT("DISPATCH_SOURCE_TYPE_MEMORYPRESSURE",
  93                 macos(10.9, 10.12), ios(6.0, 10.0), tvos(6.0, 10.0), watchos(1.0, 3.0))
  94 DISPATCH_LINUX_UNAVAILABLE()
  95 DISPATCH_SOURCE_TYPE_DECL(memorystatus);
  96
  97 /*!
  98  * @const DISPATCH_SOURCE_TYPE_SOCK
  99  * @discussion A dispatch source that monitors events on socket state changes.
 100  */
 101 #define DISPATCH_SOURCE_TYPE_SOCK (&_dispatch_source_type_sock)
 102 API_AVAILABLE(macos(10.8), ios(6.0)) DISPATCH_LINUX_UNAVAILABLE()
 103 DISPATCH_SOURCE_TYPE_DECL(sock);
 104
 105 /*!
 106  * @const DISPATCH_SOURCE_TYPE_NW_CHANNEL
 107  * @discussion A dispatch source that monitors events on a network channel.
 108  */
 109 #define DISPATCH_SOURCE_TYPE_NW_CHANNEL (&_dispatch_source_type_nw_channel)
 110 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) DISPATCH_LINUX_UNAVAILABLE()
 111 DISPATCH_SOURCE_TYPE_DECL(nw_channel);
 112
 113 __END_DECLS
 114
 115 /*!
 116  * @enum dispatch_source_sock_flags_t
 117  *
 118  * @constant DISPATCH_SOCK_CONNRESET
 119  * Received RST
 120  *
 121  * @constant DISPATCH_SOCK_READCLOSED
 122  * Read side is shutdown
 123  *
 124  * @constant DISPATCH_SOCK_WRITECLOSED
 125  * Write side is shutdown
 126  *
 127  * @constant DISPATCH_SOCK_TIMEOUT
 128  * Timeout: rexmt, keep-alive or persist
 129  *
 130  * @constant DISPATCH_SOCK_NOSRCADDR
 131  * Source address not available
 132  *
 133  * @constant DISPATCH_SOCK_IFDENIED
 134  * Interface denied connection
 135  *
 136  * @constant DISPATCH_SOCK_SUSPEND
 137  * Output queue suspended
 138  *
 139  * @constant DISPATCH_SOCK_RESUME
 140  * Output queue resumed
 141  *
 142  * @constant DISPATCH_SOCK_KEEPALIVE
 143  * TCP Keepalive received
 144  *
 145  * @constant DISPATCH_SOCK_CONNECTED
 146  * Socket is connected
 147  *
 148  * @constant DISPATCH_SOCK_DISCONNECTED
 149  * Socket is disconnected
 150  *
 151  * @constant DISPATCH_SOCK_CONNINFO_UPDATED
 152  * Connection info was updated
 153  *
 154  * @constant DISPATCH_SOCK_NOTIFY_ACK
 155  * Notify acknowledgement
 156  */
 157 enum {
 158         DISPATCH_SOCK_CONNRESET = 0x00000001,
 159         DISPATCH_SOCK_READCLOSED = 0x00000002,
 160         DISPATCH_SOCK_WRITECLOSED = 0x00000004,
 161         DISPATCH_SOCK_TIMEOUT = 0x00000008,
 162         DISPATCH_SOCK_NOSRCADDR = 0x00000010,
 163         DISPATCH_SOCK_IFDENIED = 0x00000020,
 164         DISPATCH_SOCK_SUSPEND = 0x00000040,
 165         DISPATCH_SOCK_RESUME = 0x00000080,
 166         DISPATCH_SOCK_KEEPALIVE = 0x00000100,
 167         DISPATCH_SOCK_ADAPTIVE_WTIMO = 0x00000200,
 168         DISPATCH_SOCK_ADAPTIVE_RTIMO = 0x00000400,
 169         DISPATCH_SOCK_CONNECTED = 0x00000800,
 170         DISPATCH_SOCK_DISCONNECTED = 0x00001000,
 171         DISPATCH_SOCK_CONNINFO_UPDATED = 0x00002000,
 172         DISPATCH_SOCK_NOTIFY_ACK = 0x00004000,
 173 };
 174
 175 /*!
 176  * @enum dispatch_source_nw_channel_flags_t
 177  *
 178  * @constant DISPATCH_NW_CHANNEL_FLOW_ADV_UPDATE
 179  * Received network channel flow advisory.
 180  */
 181 enum {
 182         DISPATCH_NW_CHANNEL_FLOW_ADV_UPDATE = 0x00000001,
 183 };
 184
 185 /*!
 186  * @enum dispatch_source_vfs_flags_t
 187  *
 188  * @constant DISPATCH_VFS_NOTRESP
 189  * Server down.
 190  *
 191  * @constant DISPATCH_VFS_NEEDAUTH
 192  * Server bad auth.
 193  *
 194  * @constant DISPATCH_VFS_LOWDISK
 195  * We're low on space.
 196  *
 197  * @constant DISPATCH_VFS_MOUNT
 198  * New filesystem arrived.
 199  *
 200  * @constant DISPATCH_VFS_UNMOUNT
 201  * Filesystem has left.
 202  *
 203  * @constant DISPATCH_VFS_DEAD
 204  * Filesystem is dead, needs force unmount.
 205  *
 206  * @constant DISPATCH_VFS_ASSIST
 207  * Filesystem needs assistance from external program.
 208  *
 209  * @constant DISPATCH_VFS_NOTRESPLOCK
 210  * Server lockd down.
 211  *
 212  * @constant DISPATCH_VFS_UPDATE
 213  * Filesystem information has changed.
 214  *
 215  * @constant DISPATCH_VFS_VERYLOWDISK
 216  * File system has *very* little disk space left.
 217  *
 218  * @constant DISPATCH_VFS_QUOTA
 219  * We hit a user quota (quotactl) for this filesystem.
 220  *
 221  * @constant DISPATCH_VFS_NEARLOWDISK
 222  * Filesystem is nearly full (below NEARLOWDISK level).
 223  *
 224  * @constant DISPATCH_VFS_DESIREDDISK
 225  * Filesystem has exceeded the DESIREDDISK level
 226  */
 227 enum {
 228         DISPATCH_VFS_NOTRESP = 0x0001,
 229         DISPATCH_VFS_NEEDAUTH = 0x0002,
 230         DISPATCH_VFS_LOWDISK = 0x0004,
 231         DISPATCH_VFS_MOUNT = 0x0008,
 232         DISPATCH_VFS_UNMOUNT = 0x0010,
 233         DISPATCH_VFS_DEAD = 0x0020,
 234         DISPATCH_VFS_ASSIST = 0x0040,
 235         DISPATCH_VFS_NOTRESPLOCK = 0x0080,
 236         DISPATCH_VFS_UPDATE = 0x0100,
 237         DISPATCH_VFS_VERYLOWDISK = 0x0200,
 238         DISPATCH_VFS_QUOTA = 0x1000,
 239         DISPATCH_VFS_NEARLOWDISK = 0x2000,
 240         DISPATCH_VFS_DESIREDDISK = 0x4000,
 241 };
 242
 243 /*!
 244  * @enum dispatch_source_timer_flags_t
 245  *
 246  * @constant DISPATCH_TIMER_BACKGROUND
 247  * Specifies that the timer is used to trigger low priority maintenance-level
 248  * activity and that the system may apply larger minimum leeway values to the
 249  * timer in order to align it with other system activity.
 250  *
 251  * @constant DISPATCH_INTERVAL_UI_ANIMATION
 252  * Specifies that the interval source is used for UI animation. The unit for
 253  * the interval value of such sources is frames (1/60th of a second) and the
 254  * leeway is fixed at one frame.
 255  */
 256 enum {
 257         DISPATCH_TIMER_BACKGROUND = 0x2,
 258         DISPATCH_INTERVAL_UI_ANIMATION = 0x20,
 259 };
 260
 261 /*!
 262  * @enum dispatch_source_mach_send_flags_t
 263  *
 264  * @constant DISPATCH_MACH_SEND_POSSIBLE
 265  * The mach port corresponding to the given send right has space available
 266  * for messages. Delivered only once a mach_msg() to that send right with
 267  * options MACH_SEND_MSG|MACH_SEND_TIMEOUT|MACH_SEND_NOTIFY has returned
 268  * MACH_SEND_TIMED_OUT (and not again until the next such mach_msg() timeout).
 269  * NOTE: The source must have registered the send right for monitoring with the
 270  *       system for such a mach_msg() to arm the send-possible notifcation, so
 271  *       the initial send attempt must occur from a source registration handler.
 272  */
 273 enum {
 274         DISPATCH_MACH_SEND_POSSIBLE = 0x8,
 275 };
 276
 277 /*!
 278  * @enum dispatch_source_proc_flags_t
 279  *
 280  * @constant DISPATCH_PROC_REAP
 281  * The process has been reaped by the parent process via wait*().
 282  * This flag is deprecated and will be removed in a future release.
 283  *
 284  * @constant DISPATCH_PROC_EXIT_STATUS
 285  * The process has exited. Specifying this flag allows the process exit status
 286  * to be retrieved from the source's status value, as returned by the
 287  * dispatch_source_get_extended_data() function. The macros
 288  * DISPATCH_PROC_EXIT_STATUS_EXITED(), DISPATCH_PROC_EXIT_STATUS_CODE(),
 289  * DISPATCH_PROC_EXIT_STATUS_SIGNALED(), DISPATCH_PROC_EXIT_STATUS_TERMSIG() and
 290  * DISPATCH_PROC_EXIT_STATUS_CORE_DUMPED() can be used to examine the status
 291  * value.
 292  */
 293 enum {
 294         DISPATCH_PROC_REAP DISPATCH_ENUM_API_DEPRECATED("unsupported flag",
 295                         macos(10.6,10.9), ios(4.0,7.0)) = 0x10000000,
 296         DISPATCH_PROC_EXIT_STATUS DISPATCH_ENUM_API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(2.0)) = 0x04000000,
 297 };
 298
 299 /*!
 300  * @enum dispatch_source_vm_flags_t
 301  *
 302  * @constant DISPATCH_VM_PRESSURE
 303  * The VM has experienced memory pressure.
 304  */
 305
 306 enum {
 307         DISPATCH_VM_PRESSURE DISPATCH_ENUM_API_DEPRECATED_WITH_REPLACEMENT("DISPATCH_MEMORYPRESSURE_WARN", macos(10.7, 10.10), ios(4.3, 8.0))
 308                         = 0x80000000,
 309 };
 310
 311 /*!
 312  * @typedef dispatch_source_memorypressure_flags_t
 313  * Type of dispatch_source_memorypressure flags
 314  *
 315  * @constant DISPATCH_MEMORYPRESSURE_LOW_SWAP
 316  * The system's memory pressure state has entered the "low swap" condition.
 317  * Restricted to the root user.
 318  */
 319 enum {
 320         DISPATCH_MEMORYPRESSURE_LOW_SWAP DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x08,
 321 };
 322
 323 /*!
 324  * @enum dispatch_source_memorystatus_flags_t
 325  * @warning Deprecated, see DISPATCH_MEMORYPRESSURE_*
 326  */
 327 enum {
 328         DISPATCH_MEMORYSTATUS_PRESSURE_NORMAL
 329                         DISPATCH_ENUM_API_DEPRECATED_WITH_REPLACEMENT("DISPATCH_MEMORYPRESSURE_NORMAL", macos(10.9, 10.12),
 330                         ios(6.0, 10.0), tvos(6.0, 10.0), watchos(1.0, 3.0)) = 0x01,
 331         DISPATCH_MEMORYSTATUS_PRESSURE_WARN
 332                         DISPATCH_ENUM_API_DEPRECATED_WITH_REPLACEMENT("DISPATCH_MEMORYPRESSURE_WARN", macos(10.9, 10.12),
 333                         ios(6.0, 10.0), tvos(6.0, 10.0), watchos(1.0, 3.0)) = 0x02,
 334         DISPATCH_MEMORYSTATUS_PRESSURE_CRITICAL
 335                         DISPATCH_ENUM_API_DEPRECATED_WITH_REPLACEMENT("DISPATCH_MEMORYPRESSURE_CRITICAL", macos(10.9, 10.12),
 336                         ios(6.0, 10.0), tvos(6.0, 10.0), watchos(1.0, 3.0)) = 0x04,
 337         DISPATCH_MEMORYSTATUS_LOW_SWAP
 338                         DISPATCH_ENUM_API_DEPRECATED_WITH_REPLACEMENT("DISPATCH_MEMORYPRESSURE_LOW_SWAP", macos(10.9, 10.12),
 339                         ios(6.0, 10.0), tvos(6.0, 10.0), watchos(1.0, 3.0)) = 0x08,
 340 };
 341
 342 /*!
 343  * @typedef dispatch_source_memorypressure_flags_t
 344  * Type of dispatch_source_memorypressure flags
 345  *
 346  * @constant DISPATCH_MEMORYPRESSURE_PROC_LIMIT_WARN
 347  * The memory of the process has crossed 80% of its high watermark limit.
 348  *
 349  * @constant DISPATCH_MEMORYPRESSURE_PROC_LIMIT_CRITICAL
 350  * The memory of the process has reached 100% of its high watermark limit.
 351  *
 352  * @constant DISPATCH_MEMORYPRESSURE_MSL_STATUS
 353  * Mask for enabling/disabling malloc stack logging.
 354  */
 355 enum {
 356         DISPATCH_MEMORYPRESSURE_PROC_LIMIT_WARN DISPATCH_ENUM_API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) = 0x10,
 357
 358         DISPATCH_MEMORYPRESSURE_PROC_LIMIT_CRITICAL DISPATCH_ENUM_API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) = 0x20,
 359
 360         DISPATCH_MEMORYPRESSURE_MSL_STATUS DISPATCH_ENUM_API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) = 0xf0000000,
 361 };
 362
 363 /*!
 364  * Macros to check the exit status obtained from the status field of the
 365  * structure returned by the dispatch_source_get_extended_data() function for a
 366  * source of type DISPATCH_SOURCE_TYPE_PROC when DISPATCH_PROC_EXIT_STATUS has
 367  * been requested.
 368  *
 369  * DISPATCH_PROC_EXIT_STATUS_EXITED returns whether the process exited. If this
 370  * is true, the exit status can be obtained from DISPATCH_PROC_EXIT_STATUS_CODE.
 371  *
 372  * DISPATCH_PROC_EXIT_STATUS_SIGNALED returns whether the process was terminated
 373  * by a signal.
 374  *
 375  * DISPATCH_PROC_EXIT_STATUS_TERMSIG returns the signal that caused the process
 376  * to terminate, or 0 if the process was not terminated by a signal.
 377  *
 378  * DISPATCH_PROC_EXIT_STATUS_CORE_DUMPED returns whether a core dump of the
 379  * process was created.
 380  */
 381 #define DISPATCH_PROC_EXIT_STATUS_EXITED(status) ((bool)WIFEXITED(status))
 382 #define DISPATCH_PROC_EXIT_STATUS_CODE(status) ((int)WEXITSTATUS(status))
 383 #define DISPATCH_PROC_EXIT_STATUS_SIGNALED(status) ((bool)WIFSIGNALED(status))
 384 #define DISPATCH_PROC_EXIT_STATUS_TERMSIG(status) ((int)WTERMSIG(status))
 385 #define DISPATCH_PROC_EXIT_STATUS_CORE_DUMPED(status) ((bool)WCOREDUMP(status))
 386
 387 __BEGIN_DECLS
 388
 389 /*!
 390  * @function dispatch_source_set_mandatory_cancel_handler
 391  *
 392  * @abstract
 393  * Sets the event handler block for the given dispatch source, and indicates
 394  * that calling dispatch_source_cancel() is mandatory for this source object.
 395  *
 396  * @discussion
 397  * The cancellation handler (if specified) will be submitted to the source's
 398  * target queue in response to a call to dispatch_source_cancel() once the
 399  * system has released all references to the source's underlying handle and
 400  * the source's event handler block has returned.
 401  *
 402  * When this function has been used used to set a cancellation handler, then
 403  * the following result in an assertion and the process being terminated:
 404  * - releasing the last reference on the dispatch source without having
 405  *   cancelled it by calling dispatch_source_cancel();
 406  * - changing any handler after the source has been activated;
 407  * - changing the target queue of the source after it has been activated.
 408  *
 409  * IMPORTANT:
 410  * Source cancellation and a cancellation handler are required for file
 411  * descriptor and mach port based sources in order to safely close the
 412  * descriptor or destroy the port. Making the cancellation handler of such
 413  * sources mandatory is strongly recommended.
 414  * Closing the descriptor or port before the cancellation handler is invoked may
 415  * result in a race condition. If a new descriptor is allocated with the same
 416  * value as the recently closed descriptor while the source's event handler is
 417  * still running, the event handler may read/write data to the wrong descriptor.
 418  *
 419  * @param source
 420  * The dispatch source to modify.
 421  * The result of passing NULL in this parameter is undefined.
 422  *
 423  * @param handler
 424  * The cancellation handler block to submit to the source's target queue.
 425  * The result of passing NULL in this parameter is undefined.
 426  */
 427 #ifdef __BLOCKS__
 428 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 429 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 430 void
 431 dispatch_source_set_mandatory_cancel_handler(dispatch_source_t source,
 432                 dispatch_block_t handler);
 433 #endif /* __BLOCKS__ */
 434
 435 /*!
 436  * @function dispatch_source_set_mandatory_cancel_handler_f
 437  *
 438  * @abstract
 439  * Sets the event handler function for the given dispatch source, and causes an
 440  * assertion if this source is released before having been explicitly canceled.
 441  *
 442  * @discussion
 443  * See dispatch_source_set_mandatory_cancel_handler() for more details.
 444  *
 445  * @param source
 446  * The dispatch source to modify.
 447  * The result of passing NULL in this parameter is undefined.
 448  *
 449  * @param handler
 450  * The cancellation handler function to submit to the source's target queue.
 451  * The context parameter passed to the event handler function is the current
 452  * context of the dispatch source at the time the handler call is made.
 453  * The result of passing NULL in this parameter is undefined.
 454  */
 455 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 456 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 457 void
 458 dispatch_source_set_mandatory_cancel_handler_f(dispatch_source_t source,
 459                 dispatch_function_t handler);
 460
 461 /*!
 462  * @function dispatch_source_cancel_and_wait
 463  *
 464  * @abstract
 465  * Synchronously cancel the dispatch source, preventing any further invocation
 466  * of its event handler block.
 467  *
 468  * @discussion
 469  * Cancellation prevents any further invocation of handler blocks for the
 470  * specified dispatch source, but does not interrupt a handler block that is
 471  * already in progress.
 472  *
 473  * When this function returns, any handler block that may have been in progress
 474  * has returned, the specified source has been unregistered and it is safe to
 475  * reclaim any system resource (such as file descriptors or mach ports) that
 476  * the specified source was monitoring.
 477  *
 478  * If the specified dispatch source is inactive, it will be activated as a side
 479  * effect of calling this function.
 480  *
 481  * It is possible to call this function from several threads concurrently,
 482  * and it is the responsibility of the callers to synchronize reclaiming the
 483  * associated system resources.
 484  *
 485  * This function is not subject to priority inversion when it is waiting on
 486  * a handler block still in progress, unlike patterns based on waiting on
 487  * a dispatch semaphore or a dispatch group signaled (or left) from the source
 488  * cancel handler.
 489  *
 490  * This function must not be called if the specified source has a cancel
 491  * handler set, or from the context of its handler blocks.
 492  *
 493  * This function must not be called from the context of the target queue of
 494  * the specified source or from any queue that synchronizes with it. Note that
 495  * calling dispatch_source_cancel() from such a context already guarantees
 496  * that no handler is in progress, and that no new event will be delivered.
 497  *
 498  * This function must not be called on sources suspended with an explicit
 499  * call to dispatch_suspend(), or being concurrently activated on another
 500  * thread.
 501  *
 502  * @param source
 503  * The dispatch source to be canceled.
 504  * The result of passing NULL in this parameter is undefined.
 505  */
 506 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 507 DISPATCH_EXPORT DISPATCH_NOTHROW
 508 void
 509 dispatch_source_cancel_and_wait(dispatch_source_t source);
 510
 511 #if __has_include(<mach/mach.h>)
 512 /*!
 513  * @typedef dispatch_mig_callback_t
 514  *
 515  * @abstract
 516  * The signature of a function that handles Mach message delivery and response.
 517  */
 518 typedef boolean_t (*dispatch_mig_callback_t)(mach_msg_header_t *message,
 519                 mach_msg_header_t *reply);
 520
 521 API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
 522 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 523 mach_msg_return_t
 524 dispatch_mig_server(dispatch_source_t ds, size_t maxmsgsz,
 525                 dispatch_mig_callback_t callback);
 526
 527 /*!
 528  * @function dispatch_mach_msg_get_context
 529  *
 530  * @abstract
 531  * Extract the context pointer from a mach message trailer.
 532  */
 533 API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
 534 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NONNULL_ALL
 535 DISPATCH_NOTHROW
 536 void *_Nullable
 537 dispatch_mach_msg_get_context(mach_msg_header_t *msg);
 538 #endif
 539
 540 /*!
 541  * @typedef dispatch_source_extended_data_t
 542  *
 543  * @abstract
 544  * Type used by dispatch_source_get_extended_data() to return a consistent
 545  * snapshot of the data and status of a dispatch source.
 546  */
 547 typedef struct dispatch_source_extended_data_s {
 548     unsigned long data;
 549     unsigned long status;
 550 } *dispatch_source_extended_data_t;
 551
 552 /*!
 553  * @function dispatch_source_get_extended_data
 554  *
 555  * @abstract
 556  * Returns the current data and status values for a dispatch source.
 557  *
 558  * @discussion
 559  * This function is intended to be called from within the event handler block.
 560  * The result of calling this function outside of the event handler callback is
 561  * undefined.
 562  *
 563  * @param source
 564  * The result of passing NULL in this parameter is undefined.
 565  *
 566  * @param data
 567  * A pointer to a dispatch_source_extended_data_s in which the data and status
 568  * will be returned. The data field is populated with the value that would be
 569  * returned by dispatch_source_get_data(). The value of the status field should
 570  * be interpreted according to the type of the dispatch source:
 571  *
 572  *  DISPATCH_SOURCE_TYPE_PROC:            dispatch_source_proc_exit_flags_t
 573  *
 574  * If called from the event handler of a data source type not listed above, the
 575  * status value is undefined.
 576  *
 577  * @param size
 578  * The size of the specified structure. Should be set to
 579  * sizeof(dispatch_source_extended_data_s).
 580  *
 581  * @result
 582  * The size of the structure returned in *data, which will never be greater than
 583  * the value of the size argument. If this is less than the value of the size
 584  * argument, the remaining space in data will have been populated with zeroes.
 585  */
 586 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 587 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 588 DISPATCH_NOTHROW
 589 size_t
 590 dispatch_source_get_extended_data(dispatch_source_t source,
 591                 dispatch_source_extended_data_t data, size_t size);
 592
 593 __END_DECLS
 594
 595 DISPATCH_ASSUME_NONNULL_END
 596
 597 #endif