# API Notes: dispatch library

## Apple documentation

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.

## API Notes

Note

These bindings are only available on macOS 10.8 or later. The dispatch library is available on earlier releases of macOS, but in a way that is not compatible with these bindings.

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.