PyObjC Framework: libdispatch

Warnings

• breaking PyObjC 12.x (and thus `pyobjc-framework-libdispatch` 12.x) dropped support for Python 3.9. Similarly, PyObjC 11.x dropped support for Python 3.8. The current version of PyObjC and its framework wrappers require Python 3.10 or later.
  Fix: Ensure your Python environment is version 3.10 or newer. If you must use an older Python version, install a compatible older PyObjC release.
• breaking PyObjC 10.3 introduced a change that broke `__init__` methods in Python subclasses of Objective-C classes if they implicitly relied on PyObjC's default `__new__` behavior without defining their own `__new__`. While partially reverted in 10.3.1, classes that implement `__init__` but not `__new__` and rely on PyObjC's `__new__` might still exhibit issues.
  Fix: When subclassing Objective-C classes in Python, if you define an `__init__` method, it is best practice to also explicitly define a `__new__` method in your Python class, or adhere strictly to the Objective-C `init...` pattern without overriding `__new__`.
• gotcha `libdispatch` exposes a low-level C API. Incorrect usage of its functions and types through PyObjC can bypass Python's usual error handling, leading to hard crashes or undefined behavior in your application rather than graceful Python exceptions.
  Fix: Always refer to Apple's official `libdispatch` documentation in conjunction with PyObjC's API Notes. Pay close attention to memory management, thread safety, and expected C types for arguments (e.g., pointers, blocks).
• deprecated The primary import for this framework is `import dispatch`. While `import libdispatch` currently functions for backward compatibility, it is considered the older name for the package. Future PyObjC versions may remove support for the `libdispatch` import name.
  Fix: Update all import statements from `import libdispatch` to `import dispatch` for future compatibility and to align with current best practices.
• gotcha Several `libdispatch` functions, such as `dispatch_retain`, `dispatch_release`, `dispatch_wait`, `dispatch_notify`, `dispatch_cancel`, and `dispatch_testcancel`, are either unavailable or require specific usage patterns (e.g., using object-specific variants). Additionally, the workgroup APIs introduced in macOS 11 are not supported.
  Fix: Before using a `libdispatch` function, consult the 'PyObjC API Notes: dispatch library' documentation to verify its availability and any specific Python binding requirements, such as the `array.array` argument for `dispatch_once`.

Install

• pip install pyobjc-framework-libdispatch Install `libdispatch` bindings

Imports

• dispatch

  import dispatch

  The preferred import name for libdispatch bindings is 'dispatch'. While 'libdispatch' still works for backward compatibility, 'dispatch' is the modern and recommended approach.

Quickstart

This quickstart demonstrates the use of `dispatch_once` from the `libdispatch` bindings to ensure a function runs only a single time across application execution. Note the requirement for an `array.array('l', [0])` as the predicate argument for `dispatch_once`.

import array
from dispatch import dispatch_once

# dispatch_once ensures a block of code is executed only once,
# even if called multiple times from different threads.
# It requires an array.array instance as its first argument
# to track whether the block has been run.

predicate = array.array('l', [0]) # Must be a mutable array of long (C 'long')

def my_initialization_function():
    print("Performing one-time initialization...")
    # Simulate some work
    import time
    time.sleep(0.1)
    print("Initialization complete.")

print("Attempting to call dispatch_once for the first time...")
dispatch_once(predicate, my_initialization_function)

print("Attempting to call dispatch_once for the second time...")
dispatch_once(predicate, my_initialization_function)

print("Program finished.")