Preface
Compared with other parts of GCD, dispatch_source is
probably the least eye-catching one. It is a wrapper around
kqueue, a common BSD kernel facility, and can monitor
certain kinds of events. When those events occur, it automatically
places a block onto a dispatch queue for execution. If you
already know a little about I/O multiplexing,
dispatch_source is much easier to understand.
kqueue
kqueue is one BSD implementation of I/O multiplexing.
Its interface mainly consists of two system calls, kqueue()
and kevent(), plus the struct kevent
structure.
kqueue()creates a kernel event queue and returns its file descriptor.
1 | int kqueue(void); |
kevent()registers or unregisters events with the kernel, and returns ready events or error events.
1 | int kevent(int kq, |
struct keventis the basic event structure operated on bykevent().
1 | struct kevent { |
Inside one kqueue, {ident, filter} uniquely
identifies an event:
identis the event ID. It is usually set to a file descriptor.
filtercan be understood as the event type. The kernel checks the state of the filter registered onident, and notifies the application when that state changes.kqueuedefines many filters:
1 |
- The behavior flags:
1 |
Event Types
In source.h, dispatch_source supports the
following event types:
1 | DISPATCH_SOURCE_TYPE_DATA_ADD: custom event |
Usage Steps
Because dispatch_source is used less often, it is worth
introducing its basic usage:
1 | // 1. Create a dispatch source. Here data is coalesced by addition. |
Timer
When using timers, NSTimer is usually the first thing
that comes to mind. But NSTimer is affected by the RunLoop.
When the RunLoop has many tasks to process, timer precision can drop.
For cases that need very high timing precision, we may consider
CADisplayLink; in fact, GCD timers are also an option.
1 | dispatch_queue_t queue = dispatch_get_global_queue(0, 0); |
Monitoring Files
1 | dispatch_source_t fileMonitor(const char* filename) |
Common API Source Analysis
dispatch_source_s
1 | struct dispatch_source_s { |
If you still remember the definition of
dispatch_queue_s, you can see that
dispatch_source_s is almost an overlay version of
dispatch_queue_s:
1 | struct dispatch_queue_s { |
Because the third field of dispatch_source_s is a union,
char _ds_pad[DISPATCH_QUEUE_MIN_LABEL_SIZE]; and
char dq_label[DISPATCH_QUEUE_MIN_LABEL_SIZE]; in
dispatch_queue_s are basically the same thing. This lets
functions for dispatch_queue_s initialize
dispatch_source_s, and then source-specific fields are
overwritten afterward.
dispatch_source_create
As usual, start from creation:
1 | dispatch_source_t |
Two points are worth noting:
dispatch_source_type_shas two fields: onekeventand onemask.
1 | struct dispatch_source_type_s { |
do_vtablepoints to the source-specific vtable.
1 | const struct dispatch_source_vtable_s _dispatch_source_kevent_vtable = { |
dispatch_source_set_event_handler
1 | void dispatch_source_set_event_handler(dispatch_source_t ds, dispatch_block_t handler) |
First, the handler is copied. Then
dispatch_barrier_async_f is called. This method is
extremely similar to dispatch_async_f from the queue
article: it sets the block on a continuation and pushes it into
the target queue. Also notice that
dispatch_barrier_async_f treats ds directly as
a queue. That is reasonable because their structure definitions are
highly similar.
1 | void dispatch_barrier_async_f(dispatch_queue_t dq, void *context, dispatch_function_t func) |
Now look at _dispatch_source_set_event_handler2:
1 | static void _dispatch_source_set_event_handler2(void *context) |
This method mainly stores the context for later use.
dispatch_source_set_cancel_handler
1 | void dispatch_source_set_cancel_handler(dispatch_source_t ds, |
This sets the cancel callback, showing that sources support cancellation.
1 | static void _dispatch_source_set_cancel_handler2(void *context) |
dispatch_source_cancel
1 | void dispatch_source_cancel(dispatch_source_t ds) |
It sets the cancellation flag, wakes the source, performs cancellation, unregisters the source, and finally releases resources.
dispatch_source_get_xxx
1 | unsigned long dispatch_source_get_mask(dispatch_source_t ds) |
dispatch_source_merge_data
dispatch_source_merge_data merges data into a dispatch
source of type DISPATCH_SOURCE_TYPE_DATA_ADD or
DISPATCH_SOURCE_TYPE_DATA_OR, and submits its event handler
block to the target queue.
1 | void dispatch_source_merge_data(dispatch_source_t ds, unsigned long val) |
1 | void _dispatch_source_merge_kevent(dispatch_source_t ds, const struct kevent *ke) |
dispatch_resume
1 | void dispatch_resume(dispatch_object_t dou) |
From the creation process above, a newly created source normally has
do_suspend_cnt set to
DISPATCH_OBJECT_SUSPEND_INTERVAL, meaning it starts in a
suspended state and must be manually started with
dispatch_resume.
The switch branch above should obviously go through
DISPATCH_OBJECT_SUSPEND_INTERVAL, which calls
_dispatch_wakeup.
_dispatch_wakeup was also analyzed in the queue article.
It is mainly related to do_invoke. For a source,
do_invoke points to _dispatch_source_invoke.
This method executes all source actions. Each action is guaranteed to
run on the proper queue. If the current queue does not match the action,
the correct queue is returned, and the action later runs on that
returned queue. This is the core focus of this
article.
1 | dispatch_queue_t _dispatch_source_invoke(dispatch_source_t ds) |
This function mentions the manager queue,
_dispatch_mgr_q, many times. Some cases must switch to the
manager queue, for example:
ds_is_installedis false.ds_dkevis not empty.ds_needs_rearmis true.
The manager queue is analyzed later.
_dispatch_kevent_merge
- Find existing kevents, and merge any new flags if necessary.
1 | void _dispatch_kevent_merge(dispatch_source_t ds) |
The function searches for whether an identical
dispatch kevent is already being observed. If it exists,
new flags are merged. This also shows that a kevent is
independent of a source; it does not belong exclusively to one source.
If the event does not exist, the dk is inserted into the
event queue. Finally, the source’s ds_list is inserted into
the kevent source queue, and when flags are updated the
kevent event is registered again.
_dispatch_source_init_tail_queue_array
1 | static void |
1 |
|
_dispatch_kevent_find
1 | static dispatch_kevent_t _dispatch_kevent_find(uintptr_t ident, short filter) |
_dispatch_kevent_resume
1 | void _dispatch_kevent_resume(dispatch_kevent_t dk, uint32_t new_flags, uint32_t del_flags) |
_dispatch_source_cancel_callout
This mainly performs cleanup:
1 | void |
_dispatch_source_latch_and_call
1 | void _dispatch_source_latch_and_call(dispatch_source_t ds) |
The Manager Queue
We mentioned _dispatch_mgr_q in the queue article, but
did not yet see where it was used. It is closely tied to sources, so
this section focuses on it.
1 | struct dispatch_queue_s _dispatch_mgr_q = { |
The manager queue’s do_vtable points to
_dispatch_queue_mgr_vtable:
1 | static const struct dispatch_queue_vtable_s _dispatch_queue_mgr_vtable = { |
There is no doubt that the most important fields here are
do_invoke and do_probe. They are also the
entrance to understanding the lower layers of sources.
At this point, some I/O multiplexing background becomes useful:
- Synchronous blocking, asynchronous blocking, synchronous non-blocking, and related models.
select,epoll,kqueue, and similar mechanisms.
_dispatch_mgr_wakeup
1 | static bool _dispatch_mgr_wakeup(dispatch_queue_t dq) |
1 | void |
If registering the event fails because kevent is reading
or writing data, _dispatch_select_workaround is set to true
and select is used later as a fallback. Apart from
EVFILT_READ and EVFILT_WRITE, other event
types call _dispatch_source_drain_kevent.
1 | void _dispatch_source_drain_kevent(struct kevent *ke) |
This iterates through every source in dk->dk_sources
and calls _dispatch_source_merge_kevent, meaning the event
is ready.
_dispatch_mgr_invoke
1 | static dispatch_queue_t _dispatch_mgr_invoke(dispatch_queue_t dq) |
Both the special fallback path and the normal path eventually call
_dispatch_mgr_thread2:
1 | static void _dispatch_mgr_thread2(struct kevent *kev, size_t cnt) |
1 | void _dispatch_queue_serial_drain_till_empty(dispatch_queue_t dq) |
Summary
This article is long and relatively complex, and source
itself is also less familiar than other GCD APIs. The two most important
ideas here are I/O multiplexing and the manager queue. Once you keep
those two points in mind, the underlying principle of
dispatch_source becomes much easier to understand.