Merge pull request #482 from esheldon/fix-docs

feat: clarify docs on threads and add a test

Author: beckermr

README.md

@@ -488,15 +488,41 @@ the ASCII character set.
 `fitsio` is a Python wrapper for the `cfitsio` library and so inherits the constraints
 on multithreaded programs from `cfitsio`. Specifically this means that
 
-- `fitsio.FITS` file objects are NOT thread-safe and should never be shared between threads.
 - Concurrent reading from FITS files is thread-safe, but every thread must open the FITS file
-  on its own, getting unique `fitsio.FITS` object.
+  on its own, getting a unique `fitsio.FITS` object.
 - Concurrent writing to FITS files is NOT thread-safe.
+- `fitsio.FITS` file objects can be shared between threads for reading, but only one thread
+  can use the file object at a time and so use needs to be controlled via a lock or some
+  other mechanism. See the example below.
 
 `fitsio` is compatible with Python free threading, and will not reenable the GIL
 when imported. However, the constraints above must be respected even when using Python
 free threading.
 
+Here is an example of using a lock to share a `fitsio.FITS` file pointer across threads:
+
+```python
+import concurrent.futures
+import threading
+import fitsio
+
+
+lock = threading.RLock()
+
+def _read_file(fp):
+    with lock:
+        # do something with fp here
+        pass
+
+with fitsio.FITS(fname) as fp:
+    with ThreadPoolExecutor(max_workers=10) as exc:
+        futs = [
+            exc.submit(_read_file, fp) for _ in range(10)
+        ]
+        for fut in futs:
+            res = fut.result()
+```
+
 ## TODO
 
 - HDU groups: does anyone use these? If so open an issue!

fitsio/tests/test_locking.py

@@ -0,0 +1,36 @@
+from concurrent.futures import ThreadPoolExecutor
+import numpy as np
+import os
+import tempfile
+import threading
+import time
+
+import fitsio
+
+
+def test_locking_read():
+    nt = 10
+    rng = np.random.RandomState(seed=10)
+    data = rng.normal(size=(100, 100))
+    lock = threading.RLock()
+
+    def _read_file(fp):
+        with lock:
+            time.sleep(0.1)
+            return fp[0].read()
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        fname = os.path.join(tmpdir, "fname.fits")
+
+        with fitsio.FITS(fname, "rw", clobber=True) as fp:
+            fp.write_image(data)
+
+        with fitsio.FITS(fname) as fp:
+            t0 = time.time()
+            with ThreadPoolExecutor(max_workers=nt) as exc:
+                futs = [exc.submit(_read_file, fp) for _ in range(nt)]
+                for fut in futs:
+                    res = fut.result()
+                    np.testing.assert_array_equal(res, data)
+            t0 = time.time() - t0
+            assert t0 > 1.0