Merge pull request #388 from ktopley-apple/ktopley-dispatch-42-rdar40951342
Add documentation comments.
diff --git a/src/swift/Queue.swift b/src/swift/Queue.swift
index 6d59766..0cfd782 100644
--- a/src/swift/Queue.swift
+++ b/src/swift/Queue.swift
@@ -161,21 +161,85 @@
return String(validatingUTF8: dispatch_queue_get_label(self.__wrapped))!
}
+ ///
+ /// Submits a block for synchronous execution on this queue.
+ ///
+ /// Submits a work item to a dispatch queue like `async(execute:)`, however
+ /// `sync(execute:)` will not return until the work item has finished.
+ ///
+ /// Work items submitted to a queue with `sync(execute:)` do not observe certain
+ /// queue attributes of that queue when invoked (such as autorelease frequency
+ /// and QoS class).
+ ///
+ /// Calls to `sync(execute:)` targeting the current queue will result
+ /// in deadlock. Use of `sync(execute:)` is also subject to the same
+ /// multi-party deadlock problems that may result from the use of a mutex.
+ /// Use of `async(execute:)` is preferred.
+ ///
+ /// As an optimization, `sync(execute:)` invokes the work item on the thread which
+ /// submitted it, except when the queue is the main queue or
+ /// a queue targetting it.
+ ///
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `async(execute:)`
+ ///
@available(macOS 10.10, iOS 8.0, *)
public func sync(execute workItem: DispatchWorkItem) {
CDispatch.dispatch_sync(self.__wrapped, workItem._block)
}
+ ///
+ /// Submits a work item for asynchronous execution on a dispatch queue.
+ ///
+ /// `async(execute:)` is the fundamental mechanism for submitting
+ /// work items to a dispatch queue.
+ ///
+ /// Calls to `async(execute:)` always return immediately after the work item has
+ /// been submitted, and never wait for the work item to be invoked.
+ ///
+ /// The target queue determines whether the work item will be invoked serially or
+ /// concurrently with respect to other work items submitted to that same queue.
+ /// Serial queues are processed concurrently with respect to each other.
+ ///
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `sync(execute:)`
+ ///
@available(macOS 10.10, iOS 8.0, *)
public func async(execute workItem: DispatchWorkItem) {
CDispatch.dispatch_async(self.__wrapped, workItem._block)
}
+ ///
+ /// Submits a work item to a dispatch queue and associates it with the given
+ /// dispatch group. The dispatch group may be used to wait for the completion
+ /// of the work items it references.
+ ///
+ /// - parameter group: the dispatch group to associate with the submitted block.
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `sync(execute:)`
+ ///
@available(macOS 10.10, iOS 8.0, *)
public func async(group: DispatchGroup, execute workItem: DispatchWorkItem) {
CDispatch.dispatch_group_async(group.__wrapped, self.__wrapped, workItem._block)
}
+ ///
+ /// Submits a work item to a dispatch queue and optionally associates it with a
+ /// dispatch group. The dispatch group may be used to wait for the completion
+ /// of the work items it references.
+ ///
+ /// - parameter group: the dispatch group to associate with the submitted
+ /// work item. If this is `nil`, the work item is not associated with a group.
+ /// - parameter flags: flags that control the execution environment of the
+ /// - parameter qos: the QoS at which the work item should be executed.
+ /// Defaults to `DispatchQoS.unspecified`.
+ /// - parameter flags: flags that control the execution environment of the
+ /// work item.
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `sync(execute:)`
+ /// - SeeAlso: `DispatchQoS`
+ /// - SeeAlso: `DispatchWorkItemFlags`
+ ///
public func async(
group: DispatchGroup? = nil,
qos: DispatchQoS = .unspecified,
@@ -257,10 +321,32 @@
}
}
+ ///
+ /// Submits a block for synchronous execution on this queue.
+ ///
+ /// Submits a work item to a dispatch queue like `sync(execute:)`, and returns
+ /// the value, of type `T`, returned by that work item.
+ ///
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - returns the value returned by the work item.
+ /// - SeeAlso: `sync(execute:)`
+ ///
public func sync<T>(execute work: () throws -> T) rethrows -> T {
return try self._syncHelper(fn: sync, execute: work, rescue: { throw $0 })
}
+ ///
+ /// Submits a block for synchronous execution on this queue.
+ ///
+ /// Submits a work item to a dispatch queue like `sync(execute:)`, and returns
+ /// the value, of type `T`, returned by that work item.
+ ///
+ /// - parameter flags: flags that control the execution environment of the
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - returns the value returned by the work item.
+ /// - SeeAlso: `sync(execute:)`
+ /// - SeeAlso: `DispatchWorkItemFlags`
+ ///
public func sync<T>(flags: DispatchWorkItemFlags, execute work: () throws -> T) rethrows -> T {
if flags == .barrier {
return try self._syncHelper(fn: _syncBarrier, execute: work, rescue: { throw $0 })
@@ -271,6 +357,23 @@
}
}
+ ///
+ /// Submits a work item to a dispatch queue for asynchronous execution after
+ /// a specified time.
+ ///
+ /// - parameter: deadline the time after which the work item should be executed,
+ /// given as a `DispatchTime`.
+ /// - parameter qos: the QoS at which the work item should be executed.
+ /// Defaults to `DispatchQoS.unspecified`.
+ /// - parameter flags: flags that control the execution environment of the
+ /// work item.
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `async(execute:)`
+ /// - SeeAlso: `asyncAfter(deadline:execute:)`
+ /// - SeeAlso: `DispatchQoS`
+ /// - SeeAlso: `DispatchWorkItemFlags`
+ /// - SeeAlso: `DispatchTime`
+ ///
public func asyncAfter(
deadline: DispatchTime,
qos: DispatchQoS = .unspecified,
@@ -285,6 +388,23 @@
}
}
+ ///
+ /// Submits a work item to a dispatch queue for asynchronous execution after
+ /// a specified time.
+ ///
+ /// - parameter: deadline the time after which the work item should be executed,
+ /// given as a `DispatchWallTime`.
+ /// - parameter qos: the QoS at which the work item should be executed.
+ /// Defaults to `DispatchQoS.unspecified`.
+ /// - parameter flags: flags that control the execution environment of the
+ /// work item.
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `async(execute:)`
+ /// - SeeAlso: `asyncAfter(wallDeadline:execute:)`
+ /// - SeeAlso: `DispatchQoS`
+ /// - SeeAlso: `DispatchWorkItemFlags`
+ /// - SeeAlso: `DispatchWallTime`
+ ///
public func asyncAfter(
wallDeadline: DispatchWallTime,
qos: DispatchQoS = .unspecified,
@@ -299,11 +419,31 @@
}
}
+ ///
+ /// Submits a work item to a dispatch queue for asynchronous execution after
+ /// a specified time.
+ ///
+ /// - parameter: deadline the time after which the work item should be executed,
+ /// given as a `DispatchTime`.
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `asyncAfter(deadline:qos:flags:execute:)`
+ /// - SeeAlso: `DispatchTime`
+ ///
@available(macOS 10.10, iOS 8.0, *)
public func asyncAfter(deadline: DispatchTime, execute: DispatchWorkItem) {
CDispatch.dispatch_after(deadline.rawValue, self.__wrapped, execute._block)
}
+ ///
+ /// Submits a work item to a dispatch queue for asynchronous execution after
+ /// a specified time.
+ ///
+ /// - parameter: deadline the time after which the work item should be executed,
+ /// given as a `DispatchWallTime`.
+ /// - parameter execute: The work item to be invoked on the queue.
+ /// - SeeAlso: `asyncAfter(wallDeadline:qos:flags:execute:)`
+ /// - SeeAlso: `DispatchTime`
+ ///
@available(macOS 10.10, iOS 8.0, *)
public func asyncAfter(wallDeadline: DispatchWallTime, execute: DispatchWorkItem) {
CDispatch.dispatch_after(wallDeadline.rawValue, self.__wrapped, execute._block)
