-
Notifications
You must be signed in to change notification settings - Fork 234
Update README with thread safety section #657
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.
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
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -204,6 +204,41 @@ However, a tuple is lighter than a list. | |||||
| You can use `use_list=False` while unpacking when performance is important. | ||||||
|
|
||||||
|
|
||||||
| ### Thread safety (CPython 3.14+ free-threaded build) | ||||||
|
|
||||||
| msgpack is designed to be thread-safe when used with CPython 3.14's | ||||||
| free-threaded build (PEP 703). | ||||||
|
|
||||||
| #### Thread-Safety Guarantees | ||||||
|
|
||||||
| * **Individual `Packer` and `Unpacker` instances are thread-safe**: | ||||||
| You can safely call methods on the same `Packer` or `Unpacker` instance | ||||||
| from multiple threads concurrently. All public methods are protected by | ||||||
| critical sections that ensure atomic access to internal state. | ||||||
|
|
||||||
| * **Module-level functions are thread-safe**: Functions like `packb()` and | ||||||
| `unpackb()` create their own instances internally and are safe to call | ||||||
| from multiple threads. | ||||||
|
|
||||||
| #### Performance Considerations | ||||||
|
|
||||||
| While sharing a single `Packer` or `Unpacker` instance across threads is safe, | ||||||
| it may serialize operations due to critical section locking. For optimal | ||||||
| performance in multi-threaded applications, create separate instances per thread: | ||||||
|
|
||||||
| ```python | ||||||
| import msgpack | ||||||
| from concurrent.futures import ThreadPoolExecutor | ||||||
|
|
||||||
| def worker(data): | ||||||
| # Each thread creates its own packer | ||||||
| packer = msgpack.Packer() | ||||||
| return packer.pack(data) | ||||||
|
|
||||||
| with ThreadPoolExecutor(max_workers=4) as executor: | ||||||
| results = executor.map(worker, <data>) | ||||||
|
||||||
| results = executor.map(worker, <data>) | |
| results = executor.map(worker, [1, 2, 3, 4]) |
Copilot
AI
Nov 29, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The code block uses
python which is inconsistent with the existing README convention. Other non-interactive code examples in this README usepy (see lines 60, 81). For consistency, this should be changed to ```py.