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.
|
@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. |
Your wish is about to be fulfilled: https://github.com/msgpack/msgpack-python/releases/tag/v1.2.0 |
|
|
||
| #### 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.
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.