Skip to content

Commit a20ffee

Browse files
authored
Update README.md
1 parent ce2bcef commit a20ffee

1 file changed

Lines changed: 16 additions & 4 deletions

File tree

README.md

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,31 @@
22

33
Thread-safe Python collections: `ConcurrentBag`, `ConcurrentDictionary`, and `ConcurrentQueue`.
44

5-
## Overview
5+
## tl;dr
66

7-
Python's built-in `list`, `dict`, and `deque` are thread safe for some operations, but not all.
7+
Python's built-in `list`, `dict`, and `deque` are thread-safe for some operations, but not all.
88

99
`concurrent_collections` provides thread-safe alternatives by using locks internally to ensure safe concurrent access and mutation from multiple threads.
1010

1111
## Why use these collections?
1212

13-
Python's built-in collections are **not fully thread-safe** for all operations. While some simple operations (like `list.append()` or `dict[key] = value`) are thread-safe due to the Global Interpreter Lock (GIL), **compound operations and iteration with mutation are not**. This can lead to subtle bugs, race conditions, or even crashes in multi-threaded programs.
13+
**_There is a lot of confusion on whether Python collections are thread-safe or not_**<sup>1, 2, 3</sup>. Spoiler: they aren't, despite what many people believe.
14+
15+
The bottom line is that Python's built-in collections are **not fully thread-safe** for all operations. While some simple operations (like `list.append()` or `dict[key] = value`) are thread-safe due to the Global Interpreter Lock (GIL), **compound operations and iteration with mutation are not**. This can lead to subtle bugs, race conditions, or even crashes in multi-threaded programs.
1416

1517
See the [Python FAQ: "What kinds of global value mutation are thread-safe?"](https://docs.python.org/3/faq/library.html#what-kinds-of-global-value-mutation-are-thread-safe) for details. The FAQ explains that only a handful of simple operations are guaranteed to be atomic and thread-safe. For anything more complex, you must use your own locking or a thread-safe collection.
1618

17-
`concurrent_collections` provides drop-in replacements that handle locking for you, making concurrent programming safer and easier.
19+
I could not find any simple concurrent implementation, so `concurrent_collections` provides drop-in replacements that handle locking for you, making concurrent programming safer and easier.
20+
21+
<sub>
22+
23+
1. [Are lists thread-safe?](https://stackoverflow.com/a/79645609/3873799)
24+
25+
2. [Google style guide advises against relying on Python's assignment atomicity](https://stackoverflow.com/a/55279169/3873799)
26+
27+
3. [What kind of "thread safe" are deque's actually?](https://groups.google.com/g/comp.lang.python/c/MAv5MVakB_4)
28+
29+
</sub>
1830

1931
## Installation
2032

0 commit comments

Comments
 (0)