SYNOPSIS

Fd #include <dispatch/dispatch.h> Ft dispatch_source_t Fo dispatch_source_create Fa dispatch_source_type_t type Fa uintptr_t handle Fa unsigned long mask Fa dispatch_queue_t queue Fc Ft void Fo dispatch_source_set_event_handler Fa dispatch_source_t source Fa void (^block)(void) Fc Ft void Fo dispatch_source_set_event_handler_f Fa dispatch_source_t source Fa void (*function)(void *) Fc Ft void Fo dispatch_source_set_cancel_handler Fa dispatch_source_t source Fa void (^block)(void) Fc Ft void Fo dispatch_source_set_cancel_handler_f Fa dispatch_source_t source Fa void (*function)(void *) Fc Ft void Fo dispatch_source_cancel Fa dispatch_source_t source Fc Ft void Fo dispatch_source_testcancel Fa dispatch_source_t source Fc Ft uintptr_t Fo dispatch_source_get_handle Fa dispatch_source_t source Fc Ft unsigned long Fo dispatch_source_get_mask Fa dispatch_source_t source Fc Ft unsigned long Fo dispatch_source_get_data Fa dispatch_source_t source Fc Ft void Fo dispatch_source_merge_data Fa dispatch_source_t source Fa unsigned long data Fc Ft void Fo dispatch_source_set_timer Fa dispatch_source_t source Fa dispatch_time_t start Fa uint64_t interval Fa uint64_t leeway Fc

DESCRIPTION

Dispatch event sources may be used to monitor a variety of system objects and events including file descriptors, mach ports, processes, virtual filesystem nodes, signal delivery and timers.

When a state change occurs, the dispatch source will submit its event handler block to its target queue.

The Fn dispatch_source_create function creates a new dispatch source object that may be retained and released with calls to Fn dispatch_retain and Fn dispatch_release respectively. Newly created sources are created in a suspended state. After the source has been configured by setting an event handler, cancellation handler, context, etc., the source must be activated by a call to Fn dispatch_resume before any events will be delivered.

Dispatch sources may be one of the following types:

• DISPATCH_SOURCE_TYPE_DATA_ADD
• DISPATCH_SOURCE_TYPE_DATA_OR
• DISPATCH_SOURCE_TYPE_MACH_SEND
• DISPATCH_SOURCE_TYPE_MACH_RECV
• DISPATCH_SOURCE_TYPE_PROC
• DISPATCH_SOURCE_TYPE_READ
• DISPATCH_SOURCE_TYPE_SIGNAL
• DISPATCH_SOURCE_TYPE_TIMER
• DISPATCH_SOURCE_TYPE_VNODE
• DISPATCH_SOURCE_TYPE_WRITE

The Fa handle and Fa mask arguments to Fn dispatch_source_create and the return values of the Fn dispatch_source_get_handle , Fn dispatch_source_get_mask , and Fn dispatch_source_get_data functions should be interpreted according to the type of the dispatch source.

The Fn dispatch_source_get_handle function returns the underlying handle to the dispatch source (i.e. file descriptor, mach port, process identifer, etc.). The result of this function may be cast directly to the underlying type.

The Fn dispatch_source_get_mask function returns the set of flags that were specified at source creation time via the Fa mask argument.

The Fn dispatch_source_get_data function returns the currently pending data for the dispatch source. This function should only be called from within the source's event handler. The result of calling this function from any other context is undefined.

The Fn dispatch_source_merge_data function is intended for use with the Vt DISPATCH_SOURCE_TYPE_DATA_ADD and Vt DISPATCH_SOURCE_TYPE_DATA_OR source types. The result of using this function with any other source type is undefined. Calling this function will atomically add or logical OR the data into the source's data, and trigger the delivery of the source's event handler.

SOURCE EVENT HANDLERS

In order to receive events from the dispatch source, an event handler should be specified via Fn dispatch_source_set_event_handler . The event handler block is submitted to the source's target queue when the state of the underlying system handle changes, or when an event occurs.

Dispatch sources may be suspended or resumed independently of their target queues using Fn dispatch_suspend and Fn dispatch_resume on the dispatch source directly. The data describing events which occur while a source is suspended are coalesced and delivered once the source is resumed.

The Fa handler block need not be reentrant safe, as it is not resubmitted to the target Fa queue until any prior invocation for that dispatch source has completed. When the handler is set, the dispatch source will perform a Fn Block_copy on the Fa handler block.

CANCELLATION

The Fn dispatch_source_cancel function asynchronously cancels the dispatch source, preventing any further invocation of its event handler block. Cancellation does not interrupt a currently executing handler block (non-preemptive).

The Fn dispatch_source_testcancel function may be used to determine whether the specified source has been canceled. A non-zero value will be returned if the source is canceled.

When a dispatch source is canceled its optional cancellation handler will be submitted to its target queue. The cancellation handler may be specified via Fn dispatch_source_set_cancel_handler . This cancellation handler is invoked only once, and only as a direct consequence of calling Fn dispatch_source_cancel .

Important: a cancellation handler is required for file descriptor and mach port based sources in order to safely close the descriptor or destroy the port. Closing the descriptor or port before the cancellation handler has run may result in a race condition: if a new descriptor is allocated with the same value as the recently closed descriptor while the source's event handler is still running, the event handler may read/write data to the wrong descriptor.

DISPATCH SOURCE TYPES

The following section contains a summary of supported dispatch event types and the interpretation of their parameters and returned data.

Vt DISPATCH_SOURCE_TYPE_DATA_ADD , Vt DISPATCH_SOURCE_TYPE_DATA_OR

Sources of this type allow applications to manually trigger the source's event handler via a call to Fn dispatch_source_merge_data . The data will be merged with the source's pending data via an atomic add or logic OR (based on the source's type), and the event handler block will be submitted to the source's target queue. The Fa data is application defined. These sources have no Fa handle or Fa mask and zero should be used.

Vt DISPATCH_SOURCE_TYPE_MACH_SEND

Sources of this type monitor a mach port with a send right for state changes. The Fa handle is the mach port (mach_port_t) to monitor and the Fa mask may be:

• DISPATCH_MACH_SEND_DEAD

The port's corresponding receive right has been destroyed

The data returned by Fn dispatch_source_get_data indicates which of the events in the Fa mask were observed.

Vt DISPATCH_SOURCE_TYPE_MACH_RECV

Sources of this type monitor a mach port with a receive right for state changes. The Fa handle is the mach port (mach_port_t) to monitor and the Fa mask is unused and should be zero. The event handler block will be submitted to the target queue when a message on the mach port is waiting to be received.

Vt DISPATCH_SOURCE_TYPE_PROC

Sources of this type monitor processes for state changes. The Fa handle is the process identifier (pid_t) of the process to monitor and the Fa mask may be one or more of the following:

• DISPATCH_PROC_EXIT

The process has exited and is available to wait(2).

• DISPATCH_PROC_FORK

The process has created one or more child processes.

• DISPATCH_PROC_EXEC

The process has become another executable image via a call to execve(2) or posix_spawn2.

• DISPATCH_PROC_REAP

The process status has been collected by its parent process via wait(2).

• DISPATCH_PROC_SIGNAL

A signal was delivered to the process.

The data returned by Fn dispatch_source_get_data indicates which of the events in the Fa mask were observed.

Vt DISPATCH_SOURCE_TYPE_READ

Sources of this type monitor file descriptors for pending data. The Fa handle is the file descriptor (int) to monitor and the Fa mask is unused and should be zero.

The data returned by Fn dispatch_source_get_data is an estimated number of bytes available to be read from the descriptor. This estimate should be treated as a suggested minimum read buffer size. There are no guarantees that a complete read of this size will be performed.

Users of this source type are strongly encouraged to perform non-blocking I/O and handle any truncated reads or error conditions that may occur. See fcntl(2) for additional information about setting the Vt O_NONBLOCK flag on a file descriptor.

Vt DISPATCH_SOURCE_TYPE_SIGNAL

Sources of this type monitor signals delivered to the current process. The Fa handle is the signal number to monitor (int) and the Fa mask is unused and should be zero.

The data returned by Fn dispatch_source_get_data is the number of signals received since the last invocation of the event handler block.

Unlike signal handlers specified via Fn sigaction , the execution of the event handler block does not interrupt the current thread of execution; therefore the handler block is not limited to the use of signal safe interfaces defined in sigaction(2). Furthermore, multiple observers of a given signal are supported; thus allowing applications and libraries to cooperate safely. However, a dispatch source does not install a signal handler or otherwise alter the behavior of signal delivery. Therefore, applications must ignore or at least catch any signal that terminates a process by default. For example, near the top of Fn main :

signal(SIGTERM, SIG_IGN);

Vt DISPATCH_SOURCE_TYPE_TIMER

Sources of this type periodically submit the event handler block to the target queue on an interval specified by Fn dispatch_source_set_timer . The Fa handle and Fa mask arguments are unused and should be zero.

A best effort attempt is made to submit the event handler block to the target queue at the specified time; however, actual invocation may occur at a later time.

The data returned by Fn dispatch_source_get_data is the number of times the timer has fired since the last invocation of the event handler block.

The function Fn dispatch_source_set_timer takes as an argument the Fa start time of the timer (initial fire time) represented as a Vt dispatch_time_t . The timer dispatch source will use the same clock as the function used to create this value. (See dispatch_time3 for more information.) The Fa interval , in nanoseconds, specifies the period at which the timer should repeat. All timers will repeat indefinitely until Fn dispatch_source_cancel is called. The Fa leeway , in nanoseconds, is a hint to the system that it may defer the timer in order to align with other system activity for improved system performance or reduced power consumption. (For example, an application might perform a periodic task every 5 minutes with a leeway of up to 30 seconds.) Note that some latency is to be expected for all timers even when a value of zero is used.

Note Under the C language, untyped numbers default to the Vt int type. This can lead to truncation bugs when arithmetic operations with other numbers are expected to generate a Vt uint64_t sized result. When in doubt, use Vt ull as a suffix. For example:

3ull * NSEC_PER_SEC

Vt DISPATCH_SOURCE_TYPE_VNODE

Sources of this type monitor the virtual filesystem nodes for state changes. The Fa handle is a file descriptor (int) referencing the node to monitor, and the Fa mask may be one or more of the following:

• DISPATCH_VNODE_DELETE

The referenced node was removed from the filesystem namespace via unlink(2).

• DISPATCH_VNODE_WRITE

A write to the referenced file occurred

• DISPATCH_VNODE_EXTEND

The referenced file was extended

• DISPATCH_VNODE_ATTRIB

The metadata attributes of the referenced node have changed

• DISPATCH_VNODE_LINK

The link count on the referenced node has changed

• DISPATCH_VNODE_RENAME

The referenced node was renamed

• DISPATCH_VNODE_REVOKE

Access to the referenced node was revoked via revoke(2) or the underlying fileystem was unmounted.

The data returned by Fn dispatch_source_get_data indicates which of the events in the Fa mask were observed.

Vt DISPATCH_SOURCE_TYPE_WRITE

Sources of this type monitor file descriptors for available write buffer space. The Fa handle is the file descriptor (int) to monitor and the Fa mask is unused and should be zero.

Users of this source type are strongly encouraged to perform non-blocking I/O and handle any truncated reads or error conditions that may occur. See fcntl(2) for additional information about setting the Vt O_NONBLOCK flag on a file descriptor.