Skip to content

Add free-threaded CPython (3.14t) support - #858

Open
kumaraditya303 wants to merge 3 commits into
zarr-developers:mainfrom
kumaraditya303:free-threading
Open

Add free-threaded CPython (3.14t) support#858
kumaraditya303 wants to merge 3 commits into
zarr-developers:mainfrom
kumaraditya303:free-threading

Conversation

@kumaraditya303

@kumaraditya303 kumaraditya303 commented Sep 9, 2026

Copy link
Copy Markdown

Hello, I am a CPython Core Developer working on free-threading support. This PR adds support for free-threading on 3.14t+ (#749).

Changes:

  • Mark all Cython extensions with freethreading_compatible=True so the interpreter no longer re-enables the GIL when numcodecs is imported
  • Require Cython>=3.1, needed for the freethreading_compatible directive
  • blosc: replace the lazily created multiprocessing.Lock (and get_mutex()) with a module-level threading.Lock, reset in forked children via os.register_at_fork
  • blosc: take the lock in _init, _destroy, set_nthreads and the global context path of decompress, so blosc_set_nthreads cannot re-create the global context while another thread is using it
  • blosc: compute the compressor list once at import; blosc_list_compressors() fills a static buffer without locking and was called on every compress()
  • CI: add 3.14t to the test matrix, installing without pcodec, zfpy and google_crc32c which do not ship free-threaded wheels yet
  • Wheels: enable cpython-freethreading in cibuildwheel, build cp314t-* wheels, and assert in the wheel test that the GIL is not re-enabled on free-threaded builds

TODO:

  • Unit tests and/or doctests in docstrings
  • Tests pass locally
  • Docstrings and API docs for any new/modified user-facing classes and functions
  • Changes documented in docs/release.rst
  • Docs build locally
  • GitHub Actions CI passes
  • Test coverage to 100% (Codecov passes)

- Mark all Cython extensions with freethreading_compatible=True so the
  interpreter no longer re-enables the GIL when numcodecs is imported
- Require Cython>=3.1, needed for the freethreading_compatible directive
- blosc: replace the lazily created multiprocessing.Lock (and get_mutex())
  with a module-level threading.Lock, reset in forked children via
  os.register_at_fork
- blosc: take the lock in _init, _destroy, set_nthreads and the global
  context path of decompress, so blosc_set_nthreads cannot re-create the
  global context while another thread is using it
- blosc: compute the compressor list once at import; blosc_list_compressors()
  fills a static buffer without locking and was called on every compress()
- CI: add 3.14t to the test matrix, installing without pcodec, zfpy and
  google_crc32c which do not ship free-threaded wheels yet
- Wheels: enable cpython-freethreading in cibuildwheel, build cp314t-*
  wheels, and assert in the wheel test that the GIL is not re-enabled on
  free-threaded builds
@codecov

codecov Bot commented Sep 9, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (82c3635) to head (0021eae).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #858   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           27        27           
  Lines          905       905           
=========================================
  Hits           905       905           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@kumaraditya303

Copy link
Copy Markdown
Author

I dropped -l from shell so that setup-python's PATH order is respected and free-threaded Python is installed correctly, otherwise it incorrectly picks up gil enabled python on macos 3.14t.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant