Documentation
¶
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.
Index ¶
- func After(when Dispatch_time_t, queue Queue, work func())
- func Main()
- type Data
- type DispatchWalltimeNow
- type Dispatch_block_t
- type Dispatch_data_applier_t
- type Dispatch_fd_t
- type Dispatch_function_t
- type Dispatch_io_close_flags_t
- type Dispatch_io_handler_t
- type Dispatch_io_interval_flags_t
- type Dispatch_once_t
- type Dispatch_qos_class_t
- type Dispatch_queue_concurrent_t
- type Dispatch_queue_global_t
- type Dispatch_queue_main_t
- type Dispatch_queue_priority_t
- type Dispatch_queue_serial_executor_t
- type Dispatch_queue_serial_t
- type Dispatch_source_mach_recv_flags_t
- type Dispatch_source_mach_send_flags_t
- type Dispatch_source_memorypressure_flags_t
- type Dispatch_source_proc_flags_t
- type Dispatch_source_timer_flags_t
- type Dispatch_source_vnode_flags_t
- type Dispatch_time_t
- type Dispatch_workloop_t
- type Group
- type IO
- type QOS
- type Queue
- type Semaphore
- type Source
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func After ¶
func After(when Dispatch_time_t, queue Queue, work func())
After schedules work to execute after a delay.
Types ¶
type Data ¶
type Data struct {
// contains filtered or unexported fields
}
Data wraps a dispatch data object.
func DataFromHandle ¶
DataFromHandle creates a Data from a raw handle.
type DispatchWalltimeNow ¶
type DispatchWalltimeNow uint
const ( // DISPATCH_WALLTIME_NOW: The current time. DISPATCH_WALLTIME_NOW DispatchWalltimeNow = 0 )
func (DispatchWalltimeNow) String ¶
func (e DispatchWalltimeNow) String() string
type Dispatch_block_t ¶
type Dispatch_block_t = func()
Dispatch_block_t is the prototype of blocks submitted to dispatch queues, which take no arguments and have no return value.
See: https://developer.apple.com/documentation/Dispatch/dispatch_block_t
type Dispatch_data_applier_t ¶
Dispatch_data_applier_t is a block to invoke for every contiguous memory region in a data object.
See: https://developer.apple.com/documentation/Dispatch/dispatch_data_applier_t
type Dispatch_fd_t ¶
type Dispatch_fd_t = int
Dispatch_fd_t is a file descriptor used for I/O operations.
See: https://developer.apple.com/documentation/Dispatch/dispatch_fd_t
type Dispatch_function_t ¶
Dispatch_function_t is the prototype of functions submitted to dispatch queues.
See: https://developer.apple.com/documentation/Dispatch/dispatch_function_t
type Dispatch_io_close_flags_t ¶
type Dispatch_io_close_flags_t = uint
Dispatch_io_close_flags_t is additional flags to use when closing an I/O channel.
See: https://developer.apple.com/documentation/Dispatch/dispatch_io_close_flags_t
type Dispatch_io_handler_t ¶
type Dispatch_io_handler_t = func(bool, objectivec.Object, int)
Dispatch_io_handler_t is a handler block used to process operations on a dispatch I/O channel.
See: https://developer.apple.com/documentation/Dispatch/dispatch_io_handler_t
type Dispatch_io_interval_flags_t ¶
type Dispatch_io_interval_flags_t = uint
Dispatch_io_interval_flags_t is the desired delivery behavior for interval events.
See: https://developer.apple.com/documentation/Dispatch/dispatch_io_interval_flags_t
type Dispatch_once_t ¶
type Dispatch_once_t = int
Dispatch_once_t is a predicate for use with the `dispatch_once` function.
See: https://developer.apple.com/documentation/Dispatch/dispatch_once_t
type Dispatch_qos_class_t ¶
type Dispatch_qos_class_t = uint32
Dispatch_qos_class_t is quality-of-service classes that specify the priorities for executing tasks.
See: https://developer.apple.com/documentation/Dispatch/dispatch_qos_class_t
type Dispatch_queue_concurrent_t ¶
type Dispatch_queue_concurrent_t = dispatch_queue_t
Dispatch_queue_concurrent_t is a dispatch queue that executes tasks concurrently and in any order, respecting any barriers that may be in place.
See: https://developer.apple.com/documentation/Dispatch/dispatch_queue_concurrent_t
type Dispatch_queue_global_t ¶
type Dispatch_queue_global_t = dispatch_queue_t
Dispatch_queue_global_t is a dispatch queue that executes tasks concurrently using threads from the global thread pool.
See: https://developer.apple.com/documentation/Dispatch/dispatch_queue_global_t
type Dispatch_queue_main_t ¶
type Dispatch_queue_main_t = dispatch_queue_t
Dispatch_queue_main_t is a dispatch queue that is bound to the app’s main thread and executes tasks serially on that thread.
See: https://developer.apple.com/documentation/Dispatch/dispatch_queue_main_t
type Dispatch_queue_priority_t ¶
type Dispatch_queue_priority_t = int
Dispatch_queue_priority_t is the execution priority for tasks in a global concurrent queue.
See: https://developer.apple.com/documentation/Dispatch/dispatch_queue_priority_t
type Dispatch_queue_serial_executor_t ¶
type Dispatch_queue_serial_executor_t = dispatch_queue_t
See: https://developer.apple.com/documentation/Dispatch/dispatch_queue_serial_executor_t
type Dispatch_queue_serial_t ¶
type Dispatch_queue_serial_t = dispatch_queue_t
Dispatch_queue_serial_t is a dispatch queue that executes tasks serially in first-in, first-out (FIFO) order.
See: https://developer.apple.com/documentation/Dispatch/dispatch_queue_serial_t
type Dispatch_source_mach_recv_flags_t ¶
type Dispatch_source_mach_recv_flags_t = uint
Dispatch_source_mach_recv_flags_t is mach receive-right flags.
See: https://developer.apple.com/documentation/Dispatch/dispatch_source_mach_recv_flags_t
type Dispatch_source_mach_send_flags_t ¶
type Dispatch_source_mach_send_flags_t = uint
Dispatch_source_mach_send_flags_t is mach send-right flags.
See: https://developer.apple.com/documentation/Dispatch/dispatch_source_mach_send_flags_t
type Dispatch_source_memorypressure_flags_t ¶
type Dispatch_source_memorypressure_flags_t = uint
Dispatch_source_memorypressure_flags_t is memory pressure events.
See: https://developer.apple.com/documentation/Dispatch/dispatch_source_memorypressure_flags_t
type Dispatch_source_proc_flags_t ¶
type Dispatch_source_proc_flags_t = uint
Dispatch_source_proc_flags_t is events related to a process.
See: https://developer.apple.com/documentation/Dispatch/dispatch_source_proc_flags_t
type Dispatch_source_timer_flags_t ¶
type Dispatch_source_timer_flags_t = uint
Dispatch_source_timer_flags_t is flags to use when configuring a timer dispatch source.
See: https://developer.apple.com/documentation/Dispatch/dispatch_source_timer_flags_t
type Dispatch_source_vnode_flags_t ¶
type Dispatch_source_vnode_flags_t = uint
Dispatch_source_vnode_flags_t is events involving a change to a file system object.
See: https://developer.apple.com/documentation/Dispatch/dispatch_source_vnode_flags_t
type Dispatch_time_t ¶
type Dispatch_time_t = uint64
Dispatch_time_t is an abstract representation of time.
See: https://developer.apple.com/documentation/Dispatch/dispatch_time_t
const ( // TimeNow represents the current time (no delay). TimeNow Dispatch_time_t = 0 // TimeForever represents an infinite timeout. TimeForever Dispatch_time_t = ^Dispatch_time_t(0) )
Time constants for dispatch operations.
func TimeFromNow ¶
func TimeFromNow(nanoseconds int64) Dispatch_time_t
TimeFromNow returns a dispatch time representing now + the given nanoseconds.
type Dispatch_workloop_t ¶
type Dispatch_workloop_t = dispatch_queue_t
Dispatch_workloop_t is a dispatch queue that prioritizes the execution of tasks based on their quality-of-service level.
See: https://developer.apple.com/documentation/Dispatch/dispatch_workloop_t
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
Group wraps a dispatch group for coordinating multiple async operations.
func GroupCreate ¶
func GroupCreate() Group
GroupCreate creates a new dispatch group for coordinating async operations.
func GroupFromHandle ¶
GroupFromHandle creates a Group from a raw handle.
func (Group) Enter ¶
func (g Group) Enter()
Enter manually increments the group's task count. Each Enter must be balanced with a Leave.
func (Group) Wait ¶
func (g Group) Wait(timeout Dispatch_time_t) bool
Wait blocks until all work in the group completes or timeout expires. Returns true if all work completed, false if timeout expired.
type IO ¶
type IO struct {
// contains filtered or unexported fields
}
IO wraps a dispatch I/O channel.
func IOFromHandle ¶
IOFromHandle creates an IO from a raw handle.
type QOS ¶
type QOS uint32
QoS (Quality of Service) classes for dispatch queues. Higher QoS classes get more system resources.
const ( // QOSUserInteractive is for work that is interacting with the user, // such as operating on the main thread, refreshing the UI, or performing animations. QOSUserInteractive QOS = 0x21 // QOSUserInitiated is for work that the user has initiated and is waiting for. QOSUserInitiated QOS = 0x19 // QOSDefault is the default QoS class used when no explicit class is specified. QOSDefault QOS = 0x15 // QOSUtility is for work that the user is unlikely to be immediately waiting for. QOSUtility QOS = 0x11 // QOSBackground is for work that is not visible to the user, such as indexing or syncing. QOSBackground QOS = 0x09 )
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue wraps a dispatch queue with Go-friendly methods.
func GetGlobalQueue ¶
GetGlobalQueue returns a global concurrent queue with the specified QoS class. Global queues are shared system resources and should not be released.
func MainQueue ¶
func MainQueue() Queue
MainQueue returns the main dispatch queue. Work submitted to this queue executes on the application's main thread.
func QueueCreate ¶
QueueCreate creates a new serial dispatch queue with the given label. Serial queues execute tasks one at a time in FIFO order.
func QueueCreateConcurrent ¶
QueueCreateConcurrent creates a new concurrent dispatch queue with the given label. Concurrent queues execute tasks in parallel, subject to system resources.
func QueueFromHandle ¶
QueueFromHandle creates a Queue from a raw handle.
func (Queue) Async ¶
func (q Queue) Async(work func())
Async submits a function for asynchronous execution on the queue. The function will execute on a GCD-managed thread.
func (Queue) BarrierAsync ¶
func (q Queue) BarrierAsync(work func())
BarrierAsync submits a barrier function for asynchronous execution. Only meaningful on concurrent queues - waits for all prior tasks to complete, executes exclusively, then resumes concurrent execution.
type Semaphore ¶
type Semaphore struct {
// contains filtered or unexported fields
}
Semaphore wraps a dispatch semaphore for resource counting.
func SemaphoreCreate ¶
SemaphoreCreate creates a counting semaphore with the given initial value. Use value=0 for signaling, value>0 for resource counting.
func SemaphoreFromHandle ¶
SemaphoreFromHandle creates a Semaphore from a raw handle.
func (Semaphore) Handle ¶
Handle returns the underlying dispatch semaphore handle for advanced usage.
func (Semaphore) Signal ¶
Signal increments the semaphore count. If threads are waiting, one will be woken. Returns true if a thread was woken.
func (Semaphore) Wait ¶
func (s Semaphore) Wait(timeout Dispatch_time_t) bool
Wait decrements the semaphore count, blocking if count is zero. Returns true if the semaphore was acquired, false on timeout.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source wraps a dispatch event source.
func SourceFromHandle ¶
SourceFromHandle creates a Source from a raw handle.
Source Files