perf: keep the Raw preload cache lock-free and lift the "auto" sentinel

Publish cache entries through a per-process temporary and os.replace
instead of a FileLock, so filelock stays an optional dependency rather
than a required one.

Make load_data(memmap="auto") resolve the same sentinel as
preload="auto"; previously it meant a file literally named "auto".

Stop reusing a live-mapped filename in test_auto_preload_api, which
Windows rejects when truncating a file that still has a mapping.

Author: bruAristimunha

README.rst

@@ -74,7 +74,6 @@ The minimum required dependencies to run MNE-Python are:
 
 - `Python <https://www.python.org>`__ ≥ 3.11
 - `decorator <https://pypi.org/project/decorator/>`__ ≥ 5.1
-- `filelock <https://github.com/tox-dev/py-filelock>`__ ≥ 3.18.0
 - `Jinja2 <https://jinja.palletsprojects.com/>`__ ≥ 3.1
 - `lazy-loader <https://pypi.org/project/lazy-loader/>`__ ≥ 0.3
 - `Matplotlib <https://matplotlib.org>`__ ≥ 3.9

doc/changes/dev/14216.newfeature.rst

@@ -1,2 +1 @@
-Speed up repeated preloading of FIF, EDF/BDF, and BrainVision
-recordings with a persistent copy-on-write decoded-data cache, by `Bruno Aristimunha`_.
+Speed up repeated preloading of any file-backed :class:`~mne.io.Raw` with ``preload="auto"``, which persists decoded data in a copy-on-write cache below :func:`mne.set_cache_dir`, by `Bruno Aristimunha`_.

mne/io/_preload_cache.py

@@ -12,10 +12,9 @@
 import numpy as np
 
 from .. import __version__ as MNE_VERSION  # ty: ignore[unresolved-import]
-from ..utils import _soft_import, get_config, logger
+from ..utils import get_config, logger
 
 _RAW_PRELOAD_CACHE_VERSION = 1
-_RAW_PRELOAD_LOCK_TIMEOUT = 300.0
 
 
 def _raw_preload_cache_info(raw):
@@ -82,27 +81,29 @@ def _raw_preload_auto(raw):
         logger.info(f"Reusing decoded data from {path}")
         return data
 
-    # Importing filelock is measurable, so keep it off the cache-hit path.
-    filelock = _soft_import("filelock", "locking the decoded-data cache")
-    with filelock.FileLock(f"{path}.lock", timeout=_RAW_PRELOAD_LOCK_TIMEOUT):
-        data = _raw_preload_cache_read(path, shape, dtype)
-        if data is None:
-            logger.info(f"Creating decoded data cache in {path.parent}")
-            temporary = path.with_suffix(".tmp")
-            try:
-                temporary.unlink(missing_ok=True)
-                data = np.memmap(temporary, mode="w+", dtype=dtype, shape=shape)
-                try:
-                    raw._read_segment(data_buffer=data)
-                    data.flush()
-                finally:
-                    data._mmap.close()  # ty: ignore[unresolved-attribute]
-                if _raw_preload_cache_info(raw)[1] != sources:
-                    raise RuntimeError(
-                        "Source data changed while decoded cache was created; retry"
-                    )
-                os.replace(temporary, path)
-            finally:
-                temporary.unlink(missing_ok=True)
-            data = _raw_preload_cache_read(path, shape, dtype)
+    # The temporary is per-process and os.replace is atomic, so concurrent
+    # misses need no lock; they at worst decode the same entry twice.
+    logger.info(f"Creating decoded data cache in {path.parent}")
+    temporary = path.with_suffix(f".{os.getpid()}.tmp")
+    try:
+        data = np.memmap(temporary, mode="w+", dtype=dtype, shape=shape)
+        try:
+            raw._read_segment(data_buffer=data)
+            data.flush()
+        finally:
+            data._mmap.close()  # ty: ignore[unresolved-attribute]
+        if _raw_preload_cache_info(raw)[1] != sources:
+            raise RuntimeError(
+                "Source data changed while decoded cache was created; retry"
+            )
+        try:
+            os.replace(temporary, path)
+        except OSError:
+            # Windows refuses to replace an entry another process already mapped.
+            pass
+    finally:
+        temporary.unlink(missing_ok=True)
+    data = _raw_preload_cache_read(path, shape, dtype)
+    if data is None:
+        raise RuntimeError(f"Could not read back the decoded data cache at {path}")
     return data

mne/io/base.py

@@ -605,11 +605,14 @@ def load_data(
 
         Parameters
         ----------
-        memmap : path-like | None
+        memmap : path-like | str | None
             If not ``None``, preload data into a freshly created memory-mapped file
             at this path. An existing file is overwritten. The caller owns the file
             and is responsible for removing it after the Raw object is no longer in
-            use. If ``None`` (default), preload data into RAM.
+            use. The exact string ``"auto"`` instead means the same as
+            ``preload="auto"``: reuse decoded data below the directory configured by
+            :func:`mne.set_cache_dir`. Use ``Path("auto")`` for a literal filename.
+            If ``None`` (default), preload data into RAM.
 
             .. versionadded:: 1.13
         %(verbose)s
@@ -627,7 +630,9 @@ def load_data(
         .. versionadded:: 0.10.0
         """
         if not self.preload:
-            if memmap is not None:
+            if isinstance(memmap, str) and memmap == "auto":
+                pass  # sentinel, resolved in _preload_data
+            elif memmap is not None:
                 _validate_type(memmap, "path-like", "memmap")
                 memmap = Path(memmap)
             self._preload_data(memmap if memmap is not None else True)

mne/io/tests/test_preload_cache.py

@@ -53,10 +53,10 @@ def test_auto_preload_api(tmp_path, monkeypatch):
     assert literal._data.mode == "w+"
     assert (tmp_path / "auto").is_file()
 
+    # load_data(memmap="auto") resolves the same sentinel as preload="auto"
     lazy = mne.io.read_raw_edf(source, preload=False, verbose="error")
-    with chdir(tmp_path):
+    with pytest.raises(ValueError, match="set_cache_dir"):
         lazy.load_data(memmap="auto")
-    assert lazy._data.mode == "w+"
 
 
 @pytest.mark.parametrize(

pyproject.toml

@@ -115,7 +115,6 @@ classifiers = [
 ]
 dependencies = [
   "decorator >= 5.1",
-  "filelock >= 3.18.0",
   "jinja2 >= 3.1",
   "lazy_loader >= 0.3",
   "matplotlib >= 3.9",  # released 2024-05-15, will become 3.10 on 2026-12-14
@@ -171,6 +170,7 @@ full-no-qt = [
   "dipy >= 1.9",  # released 2024-03-08, will become 1.10 on 2026-12-12
   "edfio >= 0.4.10",
   "eeglabio",
+  "filelock >= 3.18.0",
   "h5py >= 2.4",
   "imageio >= 2.6.1",
   "imageio-ffmpeg >= 0.4.1",

tools/pylock.ci-old.toml

@@ -93,12 +93,6 @@ version = "2.2.1"
 sdist = { url = "https://files.pythonhosted.org/packages/cc/28/c14e053b6762b1044f34a13aab6859bbf40456d37d23aa286ac24cfd9a5d/executing-2.2.1.tar.gz", upload-time = 2025-09-01T09:48:10Z, size = 1129488, hashes = { sha256 = "3632cc370565f6648cc328b32435bd120a1e4ebb20c77e3fdde9a13cd1e533c4" } }
 wheels = [{ url = "https://files.pythonhosted.org/packages/c1/ea/53f2148663b321f21b5a606bd5f191517cf40b7072c0497d3c92c4a13b1e/executing-2.2.1-py2.py3-none-any.whl", upload-time = 2025-09-01T09:48:08Z, size = 28317, hashes = { sha256 = "760643d3452b4d777d295bb167ccc74c64a81df23fb5e08eff250c425a4b2017" } }]
 
-[[packages]]
-name = "filelock"
-version = "3.18.0"
-sdist = { url = "https://files.pythonhosted.org/packages/0a/10/c23352565a6544bdc5353e0b15fc1c563352101f30e24bf500207a54df9a/filelock-3.18.0.tar.gz", upload-time = 2025-03-14T07:11:40Z, size = 18075, hashes = { sha256 = "adbc88eabb99d2fec8c9c1b229b171f18afa655400173ddc653d5d01501fb9f2" } }
-wheels = [{ url = "https://files.pythonhosted.org/packages/4d/36/2a115987e2d8c300a974597416d9de88f2444426de9571f4b59b2cca3acc/filelock-3.18.0-py3-none-any.whl", upload-time = 2025-03-14T07:11:39Z, size = 16215, hashes = { sha256 = "c401f4f8377c4464e6db25fff06205fd89bdd83b65eb0488ed1b160f780e21de" } }]
-
 [[packages]]
 name = "fonttools"
 version = "4.61.1"