updated

Author: flexatone

README.md

@@ -5,16 +5,14 @@ Make multi-threaded concurrency backward- and forward-compatible for the free-th
 
 ---
 
-### What?
+### Introduction
 
 `ConditionalThreadPoolExecutor` is a drop-in replacement for `ThreadPoolExecutor`
-that automatically adapts to the runtime environment.
+that adapts to the runtime environment. When running under free-threaded Python with the GIL disabled (3.14t) it behaves like a normal thread pool. However, when running under a GIL-enabled build, it falls back on single-threaded execution.
 
-When running under **free-threaded Python (3.13t)** or when threads
-are actually useful, it behaves like a normal thread pool.
+The reason this is necessary is that CPU-bound processes that use multi-threading with the GIL can be much slower than single-threaded execution.
+`ConditionalThreadPoolExecutor` permits having a single implementation that will perform optimally regardless of if the GIL is enabled or not.
 
-When running under a traditional GIL build, it **falls back to single-threaded**
-execution to avoid detrimental thread overhead.
 
 ### Why?
 
@@ -25,6 +23,24 @@ ConditionalThreadPoolExecutor detects when threads will be ineffective and avoid
 
 ### Example
 
+```python
+>>> import numpy as np
+>>> array = np.arange(100_000_000).reshape(100_000, 1_000)
+>>> func = lambda row: (row[row % 2 == 0]**2).sum()
+>>> with ConditionalThreadPoolExecutor(max_workers=22) as ex:
+...     %time _ = np.fromiter(ex.map(func, array), dtype=float, count=array.shape[0])
+...
+CPU times: user 1.35 s, sys: 0 ns, total: 1.35 s
+Wall time: 1.35 s
+>>> with ThreadPoolExecutor(max_workers=22) as ex:
+...     %time _ = np.fromiter(ex.map(func, array), dtype=float, count=array.shape[0])
+...
+CPU times: user 6.69 s, sys: 2.33 s, total: 9.02 s
+Wall time: 6.02 s
+
+```
+
+
 ```python
 from conditional_futures import ConditionalThreadPoolExecutor