table of contents
dispatch_source_create(3) | Library Functions Manual | dispatch_source_create(3) |
NAME¶
dispatch_source_create — dispatch event sourcesSYNOPSIS¶
#include <dispatch/dispatch.h> dispatch_source_tdispatch_source_create(dispatch_source_type_t type, uintptr_t handle, unsigned long mask, dispatch_queue_t queue); void
dispatch_source_set_event_handler(dispatch_source_t source, void (^block)(void)); void
dispatch_source_set_event_handler_f(dispatch_source_t source, void (*function)(void *)); void
dispatch_source_set_cancel_handler(dispatch_source_t source, void (^block)(void)); void
dispatch_source_set_cancel_handler_f(dispatch_source_t source, void (*function)(void *)); void
dispatch_source_cancel(dispatch_source_t source); void
dispatch_source_testcancel(dispatch_source_t source); uintptr_t
dispatch_source_get_handle(dispatch_source_t source); unsigned long
dispatch_source_get_mask(dispatch_source_t source); unsigned long
dispatch_source_get_data(dispatch_source_t source); void
dispatch_source_merge_data(dispatch_source_t source, unsigned long data); void
dispatch_source_set_timer(dispatch_source_t source, dispatch_time_t start, uint64_t interval, uint64_t leeway);
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 dispatch_source_create() function creates a new dispatch source object that may be retained and released with calls to dispatch_retain() and 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 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
SOURCE EVENT HANDLERS¶
In order to receive events from the dispatch source, an event handler should be specified via 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 dispatch_suspend() and 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 handler block need not be reentrant safe, as it is not resubmitted to the target queue until any prior invocation for that dispatch source has completed. When the handler is set, the dispatch source will perform a Block_copy() on the handler block.CANCELLATION¶
The 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 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 dispatch_source_set_cancel_handler(). This cancellation handler is invoked only once, and only as a direct consequence of calling 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. DISPATCH_SOURCE_TYPE_DATA_ADD, DISPATCH_SOURCE_TYPE_DATA_OR Sources of this type allow applications to manually trigger the source's event handler via a call to 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 data is application defined. These sources have no handle or mask and zero should be used. DISPATCH_SOURCE_TYPE_MACH_SEND Sources of this type monitor a mach port with a send right for state changes. The handle is the mach port (mach_port_t) to monitor and the mask may be:- • DISPATCH_MACH_SEND_DEAD
- The port's corresponding receive right has been destroyed
- • 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_spawn(2).
- • 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.
signal(SIGTERM, SIG_IGN);
3ull * NSEC_PER_SEC
- • 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.
SEE ALSO¶
dispatch(3), dispatch_object(3), dispatch_queue_create(3)May 1, 2009 | Darwin |