From a174c9300aaf74b70dd2607ac7847211b62869e6 Mon Sep 17 00:00:00 2001 From: Kim Topley Date: Wed, 18 Jul 2018 10:27:36 -0700 Subject: [PATCH] Add documentation comments. rdar://problem/40951342 --- src/swift/Queue.swift | 140 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) diff --git a/src/swift/Queue.swift b/src/swift/Queue.swift index 6d597660a..0cfd782b8 100644 --- a/src/swift/Queue.swift +++ b/src/swift/Queue.swift @@ -161,21 +161,85 @@ public extension DispatchQueue { 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 @@ public extension DispatchQueue { } } + /// + /// 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(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(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 @@ public extension DispatchQueue { } } + /// + /// 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 @@ public extension DispatchQueue { } } + /// + /// 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 @@ public extension DispatchQueue { } } + /// + /// 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)