Update README with thread safety section - #657
Conversation
Sorry, something went wrong.
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 Packer and Unpacker instances
- Explains thread safety of module-level functions like packb() and unpackb()
- 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.
Sorry, something went wrong.
| return packer.pack(data) | ||
|
|
||
| with ThreadPoolExecutor(max_workers=4) as executor: | ||
| results = executor.map(worker, <data>) |
Copilot
AI
Nov 29, 2025
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]) |
Sorry, something went wrong.
| it may serialize operations due to critical section locking. For optimal | ||
| performance in multi-threaded applications, create separate instances per thread: | ||
|
|
||
| ```python |
Copilot
AI
Nov 29, 2025
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 |
Sorry, something went wrong.
| return packer.pack(data) | ||
|
|
||
| with ThreadPoolExecutor(max_workers=4) as executor: | ||
| results = executor.map(worker, <data>) |
Copilot
AI
Nov 29, 2025
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.
Sorry, something went wrong.
|
@methane A gentle ping on this. I don't think the Copilot comments are very relevant and I still feel this PR is ready to go. |
Sorry, something went wrong.
Your wish is about to be fulfilled: https://github.com/msgpack/msgpack-python/releases/tag/v1.2.0 |
Sorry, something went wrong.
|
|
||
| #### Thread-Safety Guarantees | ||
|
|
||
| * **Individual `Packer` and `Unpacker` instances are thread-safe**: |
There was a problem hiding this comment.
thread-safe is a very strong guarantee. Packer and Unpacker are designed to not crash when used from multiple threads, but the correctness of the output depends on the types and timing of the methods being called simultaneously.
Sorry, something went wrong.
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.