Update README with thread safety section #657
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds documentation to the README explaining thread safety guarantees for msgpack when used with CPython 3.14's free-threaded build (PEP 703). The documentation clarifies that Packer and Unpacker instances are thread-safe through critical section locking, and provides performance guidance on creating separate instances per thread for optimal performance.
Key changes:
- Documents thread safety guarantees for
PackerandUnpackerinstances - Explains thread safety of module-level functions like
packb()andunpackb() - Provides a code example demonstrating the recommended pattern for multi-threaded usage
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| return packer.pack(data) | ||
|
|
||
| with ThreadPoolExecutor(max_workers=4) as executor: | ||
| results = executor.map(worker, <data>) |
There was a problem hiding this comment.
The code example contains a syntax error with the placeholder <data>. This should be replaced with a concrete example like [1, 2, 3, 4] or data_items to make the example functional and executable.
| results = executor.map(worker, <data>) | |
| results = executor.map(worker, [1, 2, 3, 4]) |
| it may serialize operations due to critical section locking. For optimal | ||
| performance in multi-threaded applications, create separate instances per thread: | ||
|
|
||
| ```python |
There was a problem hiding this comment.
The code block uses python which is inconsistent with the existing README convention. Other non-interactive code examples in this README use py (see lines 60, 81). For consistency, this should be changed to ```py.
| ```python | |
| ```py |
| return packer.pack(data) | ||
|
|
||
| with ThreadPoolExecutor(max_workers=4) as executor: | ||
| results = executor.map(worker, <data>) |
There was a problem hiding this comment.
The new thread safety documentation and recommended usage pattern lacks test coverage. Consider adding a test case that validates thread-safe usage of Packer and Unpacker instances across multiple threads, similar to the example provided in the documentation.
1 participant
Since the next version is going to be supporting the free-threaded build, I thought it might be nice to have a note about it in the README. If it's desirable, I can also update the docs.