Skip to content

Mention the free-threaded build in thread safety docs #283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Mention the free-threaded build in thread safety docs #283

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions docs/api_usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,19 +120,27 @@ parallel, you MUST construct multiple ``ZstdCompressor`` or ``ZstdDecompressor``
instances so each independent operation has its own ``ZstdCompressor`` or
``ZstdDecompressor`` instance.

The C extension releases the GIL during non-trivial calls into the zstd C
API. Non-trivial calls are notably compression and decompression. Trivial
calls are things like parsing frame parameters. Where the GIL is released
is considered an implementation detail and can change in any release.
On implementations of Python that rely on the GIL, The C extension releases the
GIL during non-trivial calls into the zstd C API. Non-trivial calls are notably
compression and decompression. Trivial calls are things like parsing frame
parameters. Where the GIL is released is considered an implementation detail and
can change in any release.

On free-threaded builds of CPython, there is no GIL, and the C extension
does not enforce any additional locking in situations where the GIL provides
locking on the GIL-enabled build. It is still a programming error to use
shared (de)compression contexts in more than one thread simultaneously.

APIs that accept bytes-like objects don't enforce that the underlying object
is read-only. However, it is assumed that the passed object is read-only for
the duration of the function call. It is possible to pass a mutable object
(like a ``bytearray``) to e.g. ``ZstdCompressor.compress()``, have the GIL
released, and mutate the object from another thread. Such a race condition
is a bug in the consumer of python-zstandard. Most Python data types are
immutable, so unless you are doing something fancy, you don't need to
worry about this.
released, and mutate the object from another thread. Similarly,
free-threaded builds of CPython can run into similar issues when
(de)compressing a bytes that are mutated simultaneously by another thread.
Such a race condition is a bug in the consumer of python-zstandard. Most
Python data types are immutable, so unless you are doing something fancy,
you don't need to worry about this.

Performance Considerations
==========================
Expand Down
Loading