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 __BEGIN_DECLS
  36
  37 /*!
  38  * @const DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE
  39  * @discussion A dispatch timer source that is part of a timer aggregate.
  40  * The handle is the dispatch timer aggregate object.
  41  * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
  42  */
  43 #define DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE \
  44                 (&_dispatch_source_type_timer_with_aggregate)
  45 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
  46 DISPATCH_SOURCE_TYPE_DECL(timer_with_aggregate);
  47
  48 /*!
  49  * @const DISPATCH_SOURCE_TYPE_INTERVAL
  50  * @discussion A dispatch source that submits the event handler block at a
  51  * specified time interval, phase-aligned with all other interval sources on
  52  * the system that have the same interval value.
  53  *
  54  * The initial submission of the event handler will occur at some point during
  55  * the first time interval after the source is created (assuming the source is
  56  * resumed at that time).
  57  *
  58  * By default, the unit for the interval value is milliseconds and the leeway
  59  * (maximum amount of time any individual handler submission may be deferred to
  60  * align with other system activity) for the source is fixed at interval/2.
  61  *
  62  * If the DISPATCH_INTERVAL_UI_ANIMATION flag is specified, the unit for the
  63  * interval value is animation frames (1/60th of a second) and the leeway is
  64  * fixed at one frame.
  65  *
  66  * The handle is the interval value in milliseconds or frames.
  67  * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
  68  */
  69 #define DISPATCH_SOURCE_TYPE_INTERVAL (&_dispatch_source_type_interval)
  70 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
  71 DISPATCH_SOURCE_TYPE_DECL(interval);
  72
  73 /*!
  74  * @const DISPATCH_SOURCE_TYPE_VFS
  75  * @discussion Apple-internal dispatch source that monitors for vfs events
  76  * defined by dispatch_vfs_flags_t.
  77  * The handle is a process identifier (pid_t).
  78  */
  79 #define DISPATCH_SOURCE_TYPE_VFS (&_dispatch_source_type_vfs)
  80 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  81 DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vfs;
  82
  83 /*!
  84  * @const DISPATCH_SOURCE_TYPE_VM
  85  * @discussion A dispatch source that monitors virtual memory
  86  * The mask is a mask of desired events from dispatch_source_vm_flags_t.
  87  * This type is deprecated, use DISPATCH_SOURCE_TYPE_MEMORYSTATUS instead.
  88  */
  89 #define DISPATCH_SOURCE_TYPE_VM (&_dispatch_source_type_vm)
  90 __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_7, __MAC_10_10, __IPHONE_4_3,
  91                 __IPHONE_8_0, "Use DISPATCH_SOURCE_TYPE_MEMORYSTATUS instead")
  92 DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vm;
  93
  94 /*!
  95  * @const DISPATCH_SOURCE_TYPE_MEMORYSTATUS
  96  * @discussion A dispatch source that monitors memory status
  97  * The mask is a mask of desired events from
  98  * dispatch_source_memorystatus_flags_t.
  99  */
 100 #define DISPATCH_SOURCE_TYPE_MEMORYSTATUS (&_dispatch_source_type_memorystatus)
 101 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 102 DISPATCH_EXPORT const struct dispatch_source_type_s
 103                 _dispatch_source_type_memorystatus;
 104
 105 /*!
 106  * @const DISPATCH_SOURCE_TYPE_SOCK
 107  * @discussion A dispatch source that monitors events on socket state changes.
 108  */
 109 #define DISPATCH_SOURCE_TYPE_SOCK (&_dispatch_source_type_sock)
 110 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 111 DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_sock;
 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 enum {
 155         DISPATCH_SOCK_CONNRESET = 0x00000001,
 156         DISPATCH_SOCK_READCLOSED = 0x00000002,
 157         DISPATCH_SOCK_WRITECLOSED = 0x00000004,
 158         DISPATCH_SOCK_TIMEOUT = 0x00000008,
 159         DISPATCH_SOCK_NOSRCADDR = 0x00000010,
 160         DISPATCH_SOCK_IFDENIED = 0x00000020,
 161         DISPATCH_SOCK_SUSPEND = 0x00000040,
 162         DISPATCH_SOCK_RESUME = 0x00000080,
 163         DISPATCH_SOCK_KEEPALIVE = 0x00000100,
 164         DISPATCH_SOCK_ADAPTIVE_WTIMO = 0x00000200,
 165         DISPATCH_SOCK_ADAPTIVE_RTIMO = 0x00000400,
 166         DISPATCH_SOCK_CONNECTED = 0x00000800,
 167         DISPATCH_SOCK_DISCONNECTED = 0x00001000,
 168         DISPATCH_SOCK_CONNINFO_UPDATED = 0x00002000,
 169 };
 170
 171 /*!
 172  * @enum dispatch_source_vfs_flags_t
 173  *
 174  * @constant DISPATCH_VFS_NOTRESP
 175  * Server down.
 176  *
 177  * @constant DISPATCH_VFS_NEEDAUTH
 178  * Server bad auth.
 179  *
 180  * @constant DISPATCH_VFS_LOWDISK
 181  * We're low on space.
 182  *
 183  * @constant DISPATCH_VFS_MOUNT
 184  * New filesystem arrived.
 185  *
 186  * @constant DISPATCH_VFS_UNMOUNT
 187  * Filesystem has left.
 188  *
 189  * @constant DISPATCH_VFS_DEAD
 190  * Filesystem is dead, needs force unmount.
 191  *
 192  * @constant DISPATCH_VFS_ASSIST
 193  * Filesystem needs assistance from external program.
 194  *
 195  * @constant DISPATCH_VFS_NOTRESPLOCK
 196  * Server lockd down.
 197  *
 198  * @constant DISPATCH_VFS_UPDATE
 199  * Filesystem information has changed.
 200  *
 201  * @constant DISPATCH_VFS_VERYLOWDISK
 202  * File system has *very* little disk space left.
 203  *
 204  * @constant DISPATCH_VFS_QUOTA
 205  * We hit a user quota (quotactl) for this filesystem.
 206  */
 207 enum {
 208         DISPATCH_VFS_NOTRESP = 0x0001,
 209         DISPATCH_VFS_NEEDAUTH = 0x0002,
 210         DISPATCH_VFS_LOWDISK = 0x0004,
 211         DISPATCH_VFS_MOUNT = 0x0008,
 212         DISPATCH_VFS_UNMOUNT = 0x0010,
 213         DISPATCH_VFS_DEAD = 0x0020,
 214         DISPATCH_VFS_ASSIST = 0x0040,
 215         DISPATCH_VFS_NOTRESPLOCK = 0x0080,
 216         DISPATCH_VFS_UPDATE = 0x0100,
 217         DISPATCH_VFS_VERYLOWDISK = 0x0200,
 218         DISPATCH_VFS_QUOTA = 0x1000,
 219 };
 220
 221 /*!
 222  * @enum dispatch_source_timer_flags_t
 223  *
 224  * @constant DISPATCH_TIMER_BACKGROUND
 225  * Specifies that the timer is used to trigger low priority maintenance-level
 226  * activity and that the system may apply larger minimum leeway values to the
 227  * timer in order to align it with other system activity.
 228  *
 229  * @constant DISPATCH_INTERVAL_UI_ANIMATION
 230  * Specifies that the interval source is used for UI animation. The unit for
 231  * the interval value of such sources is frames (1/60th of a second) and the
 232  * leeway is fixed at one frame.
 233  */
 234 enum {
 235         DISPATCH_TIMER_BACKGROUND = 0x2,
 236         DISPATCH_INTERVAL_UI_ANIMATION = 0x20,
 237 };
 238
 239 /*!
 240  * @enum dispatch_source_mach_send_flags_t
 241  *
 242  * @constant DISPATCH_MACH_SEND_POSSIBLE
 243  * The mach port corresponding to the given send right has space available
 244  * for messages. Delivered only once a mach_msg() to that send right with
 245  * options MACH_SEND_MSG|MACH_SEND_TIMEOUT|MACH_SEND_NOTIFY has returned
 246  * MACH_SEND_TIMED_OUT (and not again until the next such mach_msg() timeout).
 247  * NOTE: The source must have registered the send right for monitoring with the
 248  *       system for such a mach_msg() to arm the send-possible notifcation, so
 249  *       the initial send attempt must occur from a source registration handler.
 250  */
 251 enum {
 252         DISPATCH_MACH_SEND_POSSIBLE = 0x8,
 253 };
 254
 255 /*!
 256  * @enum dispatch_source_proc_flags_t
 257  *
 258  * @constant DISPATCH_PROC_REAP
 259  * The process has been reaped by the parent process via wait*().
 260  * This flag is deprecated and will be removed in a future release.
 261  */
 262 enum {
 263         DISPATCH_PROC_REAP __OSX_AVAILABLE_BUT_DEPRECATED(
 264                         __MAC_10_6, __MAC_10_9, __IPHONE_4_0, __IPHONE_7_0) = 0x10000000,
 265 };
 266
 267 /*!
 268  * @enum dispatch_source_vm_flags_t
 269  *
 270  * @constant DISPATCH_VM_PRESSURE
 271  * The VM has experienced memory pressure.
 272  */
 273
 274 enum {
 275         DISPATCH_VM_PRESSURE __OSX_AVAILABLE_BUT_DEPRECATED_MSG(
 276                         __MAC_10_7, __MAC_10_10, __IPHONE_4_3, __IPHONE_8_0,
 277                         "Use DISPATCH_MEMORYSTATUS_PRESSURE_WARN instead") = 0x80000000,
 278 };
 279
 280 /*!
 281  * @enum dispatch_source_memorystatus_flags_t
 282  *
 283  * @constant DISPATCH_MEMORYSTATUS_PRESSURE_NORMAL
 284  * The system's memory pressure state has returned to normal.
 285  * @constant DISPATCH_MEMORYSTATUS_PRESSURE_WARN
 286  * The system's memory pressure state has changed to warning.
 287  * @constant DISPATCH_MEMORYSTATUS_PRESSURE_CRITICAL
 288  * The system's memory pressure state has changed to critical.
 289  * @constant DISPATCH_MEMORYSTATUS_LOW_SWAP
 290  * The system's memory pressure state has entered the "low swap" condition.
 291  * Restricted to the root user.
 292  */
 293
 294 enum {
 295         DISPATCH_MEMORYSTATUS_PRESSURE_NORMAL
 296                         __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0) = 0x01,
 297         DISPATCH_MEMORYSTATUS_PRESSURE_WARN
 298                         __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0) = 0x02,
 299         DISPATCH_MEMORYSTATUS_PRESSURE_CRITICAL
 300                         __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_8_0) = 0x04,
 301         DISPATCH_MEMORYSTATUS_LOW_SWAP
 302                         __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x08,
 303 };
 304
 305 __BEGIN_DECLS
 306
 307 /*!
 308  * @typedef dispatch_timer_aggregate_t
 309  *
 310  * @abstract
 311  * Dispatch timer aggregates are sets of related timers.
 312  */
 313 DISPATCH_DECL(dispatch_timer_aggregate);
 314
 315 /*!
 316  * @function dispatch_timer_aggregate_create
 317  *
 318  * @abstract
 319  * Creates a new dispatch timer aggregate.
 320  *
 321  * @discussion
 322  * A dispatch timer aggregate is a set of related timers whose overall timing
 323  * parameters can be queried.
 324  *
 325  * Timers are added to an aggregate when a timer source is created with type
 326  * DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE.
 327  *
 328  * @result
 329  * The newly created dispatch timer aggregate.
 330  */
 331 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 332 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 333 DISPATCH_NOTHROW
 334 dispatch_timer_aggregate_t
 335 dispatch_timer_aggregate_create(void);
 336
 337 /*!
 338  * @function dispatch_timer_aggregate_get_delay
 339  *
 340  * @abstract
 341  * Retrieves the delay until a timer in the given aggregate will next fire.
 342  *
 343  * @param aggregate
 344  * The dispatch timer aggregate to query.
 345  *
 346  * @param leeway_ptr
 347  * Optional pointer to a variable filled with the leeway (in ns) that will be
 348  * applied to the return value. May be NULL.
 349  *
 350  * @result
 351  * Delay in ns from now.
 352  */
 353 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 354 DISPATCH_EXPORT DISPATCH_NOTHROW
 355 uint64_t
 356 dispatch_timer_aggregate_get_delay(dispatch_timer_aggregate_t aggregate,
 357                 uint64_t *leeway_ptr);
 358
 359 #if TARGET_OS_MAC
 360 /*!
 361  * @typedef dispatch_mig_callback_t
 362  *
 363  * @abstract
 364  * The signature of a function that handles Mach message delivery and response.
 365  */
 366 typedef boolean_t (*dispatch_mig_callback_t)(mach_msg_header_t *message,
 367                 mach_msg_header_t *reply);
 368
 369 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 370 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 371 mach_msg_return_t
 372 dispatch_mig_server(dispatch_source_t ds, size_t maxmsgsz,
 373                 dispatch_mig_callback_t callback);
 374
 375 /*!
 376  * @function dispatch_mach_msg_get_context
 377  *
 378  * @abstract
 379  * Extract the context pointer from a mach message trailer.
 380  */
 381 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 382 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NONNULL_ALL
 383 DISPATCH_NOTHROW
 384 void *
 385 dispatch_mach_msg_get_context(mach_msg_header_t *msg);
 386 #endif
 387
 388 __END_DECLS
 389
 390 #endif