API Notes: dispatch library¶

The full API is described in Apple’s documentation.

These bindings are accessed through the dispatch package (that is, import dispatch).

For backward compatibility import libdispatch works as well.

Warning

Libdispatch invokes callbacks in a context where it is not possible to raise Objective-C exceptions. This means that Python code that raises exceptions in callbacks (both blocks and functions) will cause a hard crash. Make sure that callbacks don’t raise exceptions.

API Notes¶

The libraries exposes a number APIs in two variants: one that has a block as an argument, and one that has a function as an argument. Both can be used from Python, but in general the block version is more convenient to use.

This is a fairly low-level API and programming errors can result in hard crashes instead of exceptions or error returns.

`dispatch_retain`, `dispatch_release`¶

These functions are not available.

`dispatch_debug`, `dispatch_debugv`¶

These functions are not available.

`dispatch_wait`, `dispatch_notify`, `dispatch_cancel`, `dispatch_testcancel`¶

This functions are not available, use the specific variant for the type of object you are working with instead.

`dispatch_once`, `dispatch_once_f`¶

These functions can be used from Python, but must be called with an `array.array` instance as their first arguments:

pred = array.array('l', [0])
dispatch_one(pred, callable)

`dispatch_assert_queue_debug`, `dispatch_assert_queue_barrier_debug`, `dispatch_assert_queue_not_debug`¶

These functions are not available. Call the functions without the `_debug` suffix instead.

`dispatch_introspection_hook_queue_create`, `dispatch_introspection_hook_queue_destroy`¶

These functions are not available.

`dispatch_introspection_hook_queue_item_enqueue`, `dispatch_introspection_hook_queue_item_dequeue`¶

These functions are not available.

`dispatch_introspection_hook_queue_item_complete`, `dispatch_introspection_hook_queue_item_complete`¶

These functions are not available.

`dispatch_introspection_hook_queue_callout_begin`, `dispatch_introspection_hook_queue_callout_end`¶

These functions are not available.

`dispatch_data_create`¶

Use DISPATCH_DATA_DESTRUCTOR_DEFAULT as the destructor.

The workgroup API’s¶

The various workgroup APIs (introduced in macOS 11) are not supported.