dispatch

Overview ¶

Package dispatch provides Go bindings for the Dispatch framework.

Execute code concurrently on multicore hardware by submitting work to dispatch queues managed by the system.

Dispatch, also known as Grand Central Dispatch (GCD), contains language features, runtime libraries, and system enhancements that provide systemic, comprehensive improvements to the support for concurrent code execution on multicore hardware in macOS, iOS, watchOS, and tvOS.

Notes ¶

• High-level wrappers (Queue, Group, Semaphore) are provided alongside generated interop types.

Package dispatch provides Go bindings for Apple's Grand Central Dispatch (GCD).

GCD is a low-level API for managing concurrent operations. This package exposes Go-idiomatic wrappers (exported, like QueueCreate). Raw generated C bindings are package-private and used internally by these wrappers.

Go Runtime Compatibility ¶

GCD and Go's runtime both manage threads. Key considerations:

• Use dispatch_async_f (not dispatch_async) for Go function callbacks
• Go closures passed to GCD will execute on GCD-managed threads
• Use sync.WaitGroup or channels to coordinate with Go code
• For main thread work on macOS, use the main dispatch queue

Basic Usage ¶

queue := dispatch.GetGlobalQueue(dispatch.QOSDefault)
queue.Async(func() {
    // Work executes on a GCD thread
})

Groups for Coordination ¶

group := dispatch.GroupCreate()
queue := dispatch.GetGlobalQueue(dispatch.QOSDefault)
for i := 0; i < 10; i++ {
    group.Async(queue, func() {
        // Parallel work
    })
}
group.Wait(dispatch.TimeForever)

Callback Memory ¶

Each unique dispatch function (Async, Sync, BarrierAsync, After, Group.Async, Group.Notify) uses a single permanent purego callback. Work closures are passed via a context map, not via new callbacks. This means an unlimited number of dispatches can be performed without exhausting purego's 2000-callback limit.

Known Limitations with Apple Frameworks ¶

When passing dispatch queues to Apple frameworks (like Virtualization, AVFoundation), some frameworks internally use ObjC dispatch_sync blocks which require cgo coordination. This package uses purego (cgo-free), which may cause crashes when:

• Framework wraps callbacks in ObjC dispatch_sync blocks
• Framework schedules work that calls back into Go
• Go callbacks execute on framework-managed threads

Workarounds:

• Use nil/default queue when passing to frameworks (let framework manage its queue)
• Use the main dispatch queue for framework interactions
• For Virtualization framework specifically, consider using cgo-based wrappers

For Go-to-Go dispatch operations (queue.Async, queue.Sync, groups, semaphores), this package works correctly with race detection and GC.

Code generated from Apple documentation. DO NOT EDIT.