Documentation for `DispatchQueue.concurrentPerform` confusingly references the 'target queue' over which callers have no direct control.

Question

In the 'Discussion' section of the current documentation for Swift's DispatchQueue, it says:

If the target queue is a concurrent queue, the blocks run in parallel and must therefore be reentrant-safe.

However, unlike dispatch_apply (on which this API is built), this method provides no direct means of specifying a target queue, so this callout is somewhat more confusing than it ought to be. IMO, it's important to highlight the reentrancy considerations that apply in most (all?) cases, but the implicit reference to the implementation details should be removed or clarified.

Feedback filed as: FB13708750

Dispatch

193

Posted by

jamie_sq

Reply

Thanks for filing FB13708750.

—
eskimo

Add a Comment

Answer 1

Also see the last parameter in this initializer:

https://developer.apple.com/documentation/dispatch/dispatchqueue/2300059-init

and see this function:

https://developer.apple.com/documentation/dispatch/dispatchobject/1452989-settarget

The concept of "the target queue for this queue" is well-defined, but I agree the documentation could be clearer here. Note that the parameter to dispatch_apply is "just" a queue, not a target queue in this sense used above.

Posted by

Polyphonic

@Polyphonic Could you clarify your point about dispatch_apply's queue parameter? Is the 'target queue' terminology in the 'discussion' section of that method's documentation referring to the 'dispatch object target queue' (i.e. the target queue of the queue parameter, if any) or the queue parameter itself?

—
jamie_sq

Add a Comment

Answer 2

concurrentPerform is a class method that has no queue parameter, so the wording in the documentation about "If the target queue is a concurrent queue..." is bogus, not just unclear.

Posted by

yetanotherme

Add a Comment

Answer 3

Right. concurrentPerform(iterations:execute:) is the Swift projection of dispatch_apply. That method does take a queue parameter, which is what the docs are talking about. The Swift version has no queue parameter; it always acts like you supplied the “preferred value” of DISPATCH_APPLY_AUTO.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Posted by

eskimo

Add a Comment

Documentation for `DispatchQueue.concurrentPerform` confusingly references the 'target queue' over which callers have no direct control.

Replies