1.\" Copyright (c) 2008-2013 Apple Inc. All rights reserved. 2.Dd May 1, 2009 3.Dt dispatch_source_create 3 4.Os Darwin 5.Sh NAME 6.Nm dispatch_source_create 7.Nd dispatch event sources 8.Sh SYNOPSIS 9.Fd #include <dispatch/dispatch.h> 10.Ft dispatch_source_t 11.Fo dispatch_source_create 12.Fa "dispatch_source_type_t type" 13.Fa "uintptr_t handle" 14.Fa "unsigned long mask" 15.Fa "dispatch_queue_t queue" 16.Fc 17.Ft void 18.Fo dispatch_source_set_event_handler 19.Fa "dispatch_source_t source" 20.Fa "void (^block)(void)" 21.Fc 22.Ft void 23.Fo dispatch_source_set_event_handler_f 24.Fa "dispatch_source_t source" 25.Fa "void (*function)(void *)" 26.Fc 27.Ft void 28.Fo dispatch_source_set_registration_handler 29.Fa "dispatch_source_t source" 30.Fa "void (^block)(void)" 31.Fc 32.Ft void 33.Fo dispatch_source_set_registration_handler_f 34.Fa "dispatch_source_t source" 35.Fa "void (*function)(void *)" 36.Fc 37.Ft void 38.Fo dispatch_source_set_cancel_handler 39.Fa "dispatch_source_t source" 40.Fa "void (^block)(void)" 41.Fc 42.Ft void 43.Fo dispatch_source_set_cancel_handler_f 44.Fa "dispatch_source_t source" 45.Fa "void (*function)(void *)" 46.Fc 47.Ft void 48.Fo dispatch_source_cancel 49.Fa "dispatch_source_t source" 50.Fc 51.Ft long 52.Fo dispatch_source_testcancel 53.Fa "dispatch_source_t source" 54.Fc 55.Ft uintptr_t 56.Fo dispatch_source_get_handle 57.Fa "dispatch_source_t source" 58.Fc 59.Ft "unsigned long" 60.Fo dispatch_source_get_mask 61.Fa "dispatch_source_t source" 62.Fc 63.Ft "unsigned long" 64.Fo dispatch_source_get_data 65.Fa "dispatch_source_t source" 66.Fc 67.Ft void 68.Fo dispatch_source_merge_data 69.Fa "dispatch_source_t source" 70.Fa "unsigned long data" 71.Fc 72.Ft void 73.Fo dispatch_source_set_timer 74.Fa "dispatch_source_t source" 75.Fa "dispatch_time_t start" 76.Fa "uint64_t interval" 77.Fa "uint64_t leeway" 78.Fc 79.Sh DESCRIPTION 80Dispatch event sources may be used to monitor a variety of system objects and 81events including file descriptors, mach ports, processes, virtual filesystem 82nodes, signal delivery and timers. 83.Pp 84When a state change occurs, the dispatch source will submit its event handler 85block to its target queue. 86.Pp 87The 88.Fn dispatch_source_create 89function creates a new dispatch source object that may be retained and released 90with calls to 91.Fn dispatch_retain 92and 93.Fn dispatch_release 94respectively. The 95.Fa queue 96parameter specifies the target queue of the new source object, it will 97be retained by the source object. Pass the 98.Dv DISPATCH_TARGET_QUEUE_DEFAULT 99constant to use the default target queue (the default priority global 100concurrent queue). 101.Pp 102Newly created sources are created in a suspended state. After the source has 103been configured by setting an event handler, cancellation handler, registration 104handler, context, 105etc., the source must be activated by a call to 106.Fn dispatch_resume 107before any events will be delivered. 108.Pp 109Dispatch sources may be one of the following types: 110.Bl -bullet -compact -offset indent 111.It 112DISPATCH_SOURCE_TYPE_DATA_ADD 113.It 114DISPATCH_SOURCE_TYPE_DATA_OR 115.It 116DISPATCH_SOURCE_TYPE_MACH_SEND 117.It 118DISPATCH_SOURCE_TYPE_MACH_RECV 119.It 120DISPATCH_SOURCE_TYPE_MEMORYPRESSURE 121.It 122DISPATCH_SOURCE_TYPE_PROC 123.It 124DISPATCH_SOURCE_TYPE_READ 125.It 126DISPATCH_SOURCE_TYPE_SIGNAL 127.It 128DISPATCH_SOURCE_TYPE_TIMER 129.It 130DISPATCH_SOURCE_TYPE_VNODE 131.It 132DISPATCH_SOURCE_TYPE_WRITE 133.El 134.Pp 135The 136.Fa handle 137and 138.Fa mask 139arguments to 140.Fn dispatch_source_create 141and the return values of the 142.Fn dispatch_source_get_handle , 143.Fn dispatch_source_get_mask , 144and 145.Fn dispatch_source_get_data 146functions should be interpreted according to the type of the dispatch source. 147.Pp 148The 149.Fn dispatch_source_get_handle 150function 151returns the underlying handle to the dispatch source (i.e. file descriptor, 152mach port, process identifer, etc.). The result of this function may be cast 153directly to the underlying type. 154.Pp 155The 156.Fn dispatch_source_get_mask 157function 158returns the set of flags that were specified at source creation time via the 159.Fa mask 160argument. 161.Pp 162The 163.Fn dispatch_source_get_data 164function returns the currently pending data for the dispatch source. 165This function should only be called from within the source's event handler. 166The result of calling this function from any other context is undefined. 167.Pp 168The 169.Fn dispatch_source_merge_data 170function is intended for use with the 171.Vt DISPATCH_SOURCE_TYPE_DATA_ADD 172and 173.Vt DISPATCH_SOURCE_TYPE_DATA_OR 174source types. The result of using this function with any other source type is 175undefined. Calling this function will atomically add or bitwise OR the data 176into the source's data, and trigger the delivery of the source's event handler. 177.Pp 178.Sh SOURCE EVENT HANDLERS 179In order to receive events from the dispatch source, an event handler should be 180specified via 181.Fn dispatch_source_set_event_handler . 182The event handler block is submitted to the source's target queue when the state 183of the underlying system handle changes, or when an event occurs. If a source 184is resumed with no event handler block set, events will be quietly ignored. 185If the event handler block is changed while the source is suspended, or from a 186block running on a serial queue that is the source's target queue, then the next 187event handler invocation will use the new block. 188.Pp 189Dispatch sources may be suspended or resumed independently of their target 190queues using 191.Fn dispatch_suspend 192and 193.Fn dispatch_resume 194on the dispatch source directly. The data describing events which occur while a 195source is suspended are coalesced and delivered once the source is resumed. 196.Pp 197The 198.Fa handler 199block 200need not be reentrant safe, as it is not resubmitted to the target 201.Fa queue 202until any prior invocation for that dispatch source has completed. 203When the handler is set, the dispatch source will perform a 204.Fn Block_copy 205on the 206.Fa handler 207block. 208.Pp 209To unset the event handler, call 210.Fn dispatch_source_set_event_handler_f 211and pass NULL as 212.Fa function . 213This unsets the event handler regardless of whether the handler 214was a function pointer or a block. Registration and cancellation handlers 215(see below) may be unset in the same way, but as noted below, a cancellation 216handler may be required. 217.Sh REGISTRATION 218When 219.Fn dispatch_resume 220is called on a suspended or newly created source, there may be a brief delay 221before the source is ready to receive events from the underlying system handle. 222During this delay, the event handler will not be invoked, and events will be 223missed. 224.Pp 225Once the dispatch source is registered with the underlying system and is ready 226to process all events its optional registration handler will be submitted to 227its target queue. This registration handler may be specified via 228.Fn dispatch_source_set_registration_handler . 229.Pp 230The event handler will not be called until the registration handler finishes. 231If the source is canceled (see below) before it is registered, 232its registration handler will not be called. 233.Pp 234.Sh CANCELLATION 235The 236.Fn dispatch_source_cancel 237function asynchronously cancels the dispatch source, preventing any further 238invocation of its event handler block. Cancellation does not interrupt a 239currently executing handler block (non-preemptive). If a source is canceled 240before the first time it is resumed, its event handler will never be called. 241(In this case, note that the source must be resumed before it can be released.) 242.Pp 243The 244.Fn dispatch_source_testcancel 245function may be used to determine whether the specified source has been 246canceled. A non-zero value will be returned if the source is canceled. 247.Pp 248When a dispatch source is canceled its optional cancellation handler will be 249submitted to its target queue. The cancellation handler may be specified via 250.Fn dispatch_source_set_cancel_handler . 251This cancellation handler is invoked only once, and only as a direct consequence 252of calling 253.Fn dispatch_source_cancel . 254.Pp 255.Em Important: 256a cancellation handler is required for file descriptor and mach port based 257sources in order to safely close the descriptor or destroy the port. Closing the 258descriptor or port before the cancellation handler has run may result in a race 259condition: if a new descriptor is allocated with the same value as the recently 260closed descriptor while the source's event handler is still running, the event 261handler may read/write data to the wrong descriptor. 262.Pp 263.Sh DISPATCH SOURCE TYPES 264The following section contains a summary of supported dispatch event types and 265the interpretation of their parameters and returned data. 266.Pp 267.Vt DISPATCH_SOURCE_TYPE_DATA_ADD , 268.Vt DISPATCH_SOURCE_TYPE_DATA_OR 269.Pp 270Sources of this type allow applications to manually trigger the source's event 271handler via a call to 272.Fn dispatch_source_merge_data . 273The data will be merged with the source's pending data via an atomic add or 274logic OR (based on the source's type), and the event handler block will be 275submitted to the source's target queue. The 276.Fa data 277is application defined. These sources have no 278.Fa handle 279or 280.Fa mask 281and zero should be used. 282.Pp 283.Vt DISPATCH_SOURCE_TYPE_MACH_SEND 284.Pp 285Sources of this type monitor a mach port with a send right for state changes. 286The 287.Fa handle 288is the mach port (mach_port_t) to monitor and the 289.Fa mask 290may be: 291.Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent 292.It \(bu DISPATCH_MACH_SEND_DEAD 293The port's corresponding receive right has been destroyed 294.El 295.Pp 296The data returned by 297.Fn dispatch_source_get_data 298indicates which of the events in the 299.Fa mask 300were observed. 301.Pp 302.Vt DISPATCH_SOURCE_TYPE_MACH_RECV 303.Pp 304Sources of this type monitor a mach port with a receive right for state changes. 305The 306.Fa handle 307is the mach port (mach_port_t) to monitor and the 308.Fa mask 309is unused and should be zero. 310The event handler block will be submitted to the target queue when a message 311on the mach port is waiting to be received. 312.Pp 313.Vt DISPATCH_SOURCE_TYPE_MEMORYPRESSURE 314.Pp 315Sources of this type monitor the system memory pressure condition for state changes. 316The 317.Fa handle 318is unused and should be zero. The 319.Fa mask 320may be one or more of the following: 321.Bl -tag -width "XXDISPATCH_MEMORYPRESSURE_CRITICAL" -compact -offset indent 322.It \(bu DISPATCH_MEMORYPRESSURE_NORMAL 323The system memory pressure condition has returned to normal. 324.It \(bu DISPATCH_MEMORYPRESSURE_WARN 325The system memory pressure condition has changed to warning. 326.It \(bu DISPATCH_MEMORYPRESSURE_CRITICAL 327The system memory pressure condition has changed to critical. 328.El 329.Pp 330The data returned by 331.Fn dispatch_source_get_data 332indicates which of the events in the 333.Fa mask 334were observed. 335.Pp 336Elevated memory pressure is a system-wide condition that applications 337registered for this source should react to by changing their future memory use 338behavior, e.g. by reducing cache sizes of newly initiated operations until 339memory pressure returns back to normal. 340.Pp 341However, applications should 342.Em NOT 343traverse and discard existing caches for past operations when the system memory 344pressure enters an elevated state, as that is likely to trigger VM operations 345that will further aggravate system memory pressure. 346.Pp 347.Vt DISPATCH_SOURCE_TYPE_PROC 348.Pp 349Sources of this type monitor processes for state changes. 350The 351.Fa handle 352is the process identifier (pid_t) of the process to monitor and the 353.Fa mask 354may be one or more of the following: 355.Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent 356.It \(bu DISPATCH_PROC_EXIT 357The process has exited and is available to 358.Xr wait 2 . 359.It \(bu DISPATCH_PROC_FORK 360The process has created one or more child processes. 361.It \(bu DISPATCH_PROC_EXEC 362The process has become another executable image via a call to 363.Xr execve 2 364or 365.Xr posix_spawn 2 . 366.It \(bu DISPATCH_PROC_SIGNAL 367A signal was delivered to the process. 368.El 369.Pp 370The data returned by 371.Fn dispatch_source_get_data 372indicates which of the events in the 373.Fa mask 374were observed. 375.Pp 376.Vt DISPATCH_SOURCE_TYPE_READ 377.Pp 378Sources of this type monitor file descriptors for pending data. 379The 380.Fa handle 381is the file descriptor (int) to monitor and the 382.Fa mask 383is unused and should be zero. 384.Pp 385The data returned by 386.Fn dispatch_source_get_data 387is an estimated number of bytes available to be read from the descriptor. This 388estimate should be treated as a suggested 389.Em minimum 390read buffer size. There are no guarantees that a complete read of this size 391will be performed. 392.Pp 393Users of this source type are strongly encouraged to perform non-blocking I/O 394and handle any truncated reads or error conditions that may occur. See 395.Xr fcntl 2 396for additional information about setting the 397.Vt O_NONBLOCK 398flag on a file descriptor. 399.Pp 400.Vt DISPATCH_SOURCE_TYPE_SIGNAL 401.Pp 402Sources of this type monitor signals delivered to the current process. The 403.Fa handle 404is the signal number to monitor (int) and the 405.Fa mask 406is unused and should be zero. 407.Pp 408The data returned by 409.Fn dispatch_source_get_data 410is the number of signals received since the last invocation of the event handler 411block. 412.Pp 413Unlike signal handlers specified via 414.Fn sigaction , 415the execution of the event handler block does not interrupt the current thread 416of execution; therefore the handler block is not limited to the use of signal 417safe interfaces defined in 418.Xr sigaction 2 . 419Furthermore, multiple observers of a given signal are supported; thus allowing 420applications and libraries to cooperate safely. However, a dispatch source 421.Em does not 422install a signal handler or otherwise alter the behavior of signal delivery. 423Therefore, applications must ignore or at least catch any signal that terminates 424a process by default. For example, near the top of 425.Fn main : 426.Bd -literal -offset ident 427signal(SIGTERM, SIG_IGN); 428.Ed 429.Pp 430.Vt DISPATCH_SOURCE_TYPE_TIMER 431.Pp 432Sources of this type periodically submit the event handler block to the target 433queue. The 434.Fa handle 435argument is unused and should be zero. 436.Pp 437The data returned by 438.Fn dispatch_source_get_data 439is the number of times the timer has fired since the last invocation of the 440event handler block. 441.Pp 442The timer parameters are configured with the 443.Fn dispatch_source_set_timer 444function. Once this function returns, any pending source data accumulated for 445the previous timer parameters has been cleared; the next fire of the timer will 446occur at 447.Fa start , 448and every 449.Fa interval 450nanoseconds thereafter until the timer source is canceled. 451.Pp 452Any fire of the timer may be delayed by the system in order to improve power 453consumption and system performance. The upper limit to the allowable delay may 454be configured with the 455.Fa leeway 456argument, the lower limit is under the control of the system. 457.Pp 458For the initial timer fire at 459.Fa start , 460the upper limit to the allowable delay is set to 461.Fa leeway 462nanoseconds. For the subsequent timer fires at 463.Fa start 464.Li "+ N *" 465.Fa interval , 466the upper limit is 467.Li MIN( 468.Fa leeway , 469.Fa interval 470.Li "/ 2 )" . 471.Pp 472The lower limit to the allowable delay may vary with process state such as 473visibility of application UI. If the specified timer source was created with a 474.Fa mask 475of 476.Vt DISPATCH_TIMER_STRICT , 477the system will make a best effort to strictly observe the provided 478.Fa leeway 479value even if it is smaller than the current lower limit. Note that a minimal 480amount of delay is to be expected even if this flag is specified. 481.Pp 482The 483.Fa start 484argument also determines which clock will be used for the timer: If 485.Fa start 486is 487.Vt DISPATCH_TIME_NOW 488or was created with 489.Xr dispatch_time 3 , 490the timer is based on 491.Fn mach_absolute_time . 492If 493.Fa start 494was created with 495.Xr dispatch_walltime 3 , 496the timer is based on 497.Xr gettimeofday 3 . 498.Pp 499.Em Note : 500Under the C language, untyped numbers default to the 501.Vt int 502type. This can lead to truncation bugs when arithmetic operations with other 503numbers are expected to generate a 504.Vt uint64_t 505sized result. When in doubt, use 506.Vt ull 507as a suffix. For example: 508.Bd -literal -offset indent 5093ull * NSEC_PER_SEC 510.Ed 511.Pp 512.Vt DISPATCH_SOURCE_TYPE_VNODE 513.Pp 514Sources of this type monitor the virtual filesystem nodes for state changes. 515The 516.Fa handle 517is a file descriptor (int) referencing the node to monitor, and 518the 519.Fa mask 520may be one or more of the following: 521.Bl -tag -width "XXDISPATCH_VNODE_ATTRIB" -compact -offset indent 522.It \(bu DISPATCH_VNODE_DELETE 523The referenced node was removed from the filesystem namespace via 524.Xr unlink 2 . 525.It \(bu DISPATCH_VNODE_WRITE 526A write to the referenced file occurred 527.It \(bu DISPATCH_VNODE_EXTEND 528The referenced file was extended 529.It \(bu DISPATCH_VNODE_ATTRIB 530The metadata attributes of the referenced node have changed 531.It \(bu DISPATCH_VNODE_LINK 532The link count on the referenced node has changed 533.It \(bu DISPATCH_VNODE_RENAME 534The referenced node was renamed 535.It \(bu DISPATCH_VNODE_REVOKE 536Access to the referenced node was revoked via 537.Xr revoke 2 538or the underlying fileystem was unmounted. 539.El 540.Pp 541The data returned by 542.Fn dispatch_source_get_data 543indicates which of the events in the 544.Fa mask 545were observed. 546.Pp 547.Vt DISPATCH_SOURCE_TYPE_WRITE 548.Pp 549Sources of this type monitor file descriptors for available write buffer space. 550The 551.Fa handle 552is the file descriptor (int) to monitor and the 553.Fa mask 554is unused and should be zero. 555.Pp 556Users of this source type are strongly encouraged to perform non-blocking I/O 557and handle any truncated reads or error conditions that may occur. See 558.Xr fcntl 2 559for additional information about setting the 560.Vt O_NONBLOCK 561flag on a file descriptor. 562.Pp 563.Sh SEE ALSO 564.Xr dispatch 3 , 565.Xr dispatch_object 3 , 566.Xr dispatch_queue_create 3 567