Skip to content

Commit 4111469

Browse files
committed
docs: mention the free-threaded build in thread safety docs
1 parent 7a77a75 commit 4111469

File tree

1 file changed

+16
-8
lines changed

1 file changed

+16
-8
lines changed

docs/api_usage.rst

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -120,19 +120,27 @@ parallel, you MUST construct multiple ``ZstdCompressor`` or ``ZstdDecompressor``
120120
instances so each independent operation has its own ``ZstdCompressor`` or
121121
``ZstdDecompressor`` instance.
122122

123-
The C extension releases the GIL during non-trivial calls into the zstd C
124-
API. Non-trivial calls are notably compression and decompression. Trivial
125-
calls are things like parsing frame parameters. Where the GIL is released
126-
is considered an implementation detail and can change in any release.
123+
On implementations of Python that rely on the GIL, The C extension releases the
124+
GIL during non-trivial calls into the zstd C API. Non-trivial calls are notably
125+
compression and decompression. Trivial calls are things like parsing frame
126+
parameters. Where the GIL is released is considered an implementation detail and
127+
can change in any release.
128+
129+
On free-threaded builds of CPython, there is no GIL, and the C extension
130+
does not enforce any additional locking in situations where the GIL provides
131+
locking on the GIL-enabled build. It is still a programming error to use
132+
shared (de)compression contexts in more than one thread simultaneously.
127133

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

137145
Performance Considerations
138146
==========================

0 commit comments

Comments
 (0)