various improvements (#10)

Author: fabien-marty

README.md

@@ -90,7 +90,7 @@ if obj is not CACHE_MISS:
 
 ## Full API reference
 
-Refer to the [API reference](reference/api.md) for the full API.
+Refer to the [API reference](https://fabien-marty.github.io/atomic-lru/reference/api/) for the full API.
 
 ## DEV
 

atomic_lru/_storage/storage.py

@@ -98,6 +98,10 @@ class Storage(Generic[T]):
     __closed: bool = False
 
     def __post_init__(self) -> None:
+        # Validate configuration before allocating any resources
+        if self.size_limit_in_bytes is not None and self.size_limit_in_bytes < 4096:
+            raise ValueError("size_limit_in_bytes must be greater than 4096")
+
         self._size_in_bytes = sys.getsizeof(self._data)
         if not self.expiration_disabled:
             self.__expiration_thread = ExpirationThread(
@@ -107,29 +111,31 @@ def __post_init__(self) -> None:
                 log=self.expiration_thread_log,
             )
             self.__expiration_thread.start()
-        if self.size_limit_in_bytes is not None and self.size_limit_in_bytes < 4096:
-            raise ValueError("size_limit_in_bytes must be greater than 4096")
 
     def close(self, wait: bool = False) -> None:
         """Close the storage and stop the expiration thread.
 
         Marks the storage as closed and stops the background expiration thread
-        if it was started. After closing, all operations except `size_in_bytes`
-        and `number_of_items` will raise a `RuntimeError`.
+        if it was started. After closing, all operations except `size_in_bytes`,
+        `number_of_items`, and `get()` will raise a `RuntimeError`.
 
         Args:
             wait: If True, blocks until the expiration thread has fully stopped.
                 If False, returns immediately after signaling the thread to stop.
                 Defaults to False.
 
         Note:
-            This method is idempotent - calling it multiple times has no effect.
+            This method is idempotent - calling it multiple times
+            or from multiple threads has no effect beyond the first call.
             It's recommended to call this method when you're done with the storage
             to ensure proper cleanup of background threads.
         """
-        if self.__closed:
-            return
-        self.__closed = True
+        with self.__lock:
+            if self.__closed:
+                return
+            self.__closed = True
+        # Stop thread outside the lock to avoid potential deadlock
+        # (thread's _clean_expired also acquires the lock)
         if not self.expiration_disabled:
             assert self.__expiration_thread is not None
             self.__expiration_thread.stop(wait=wait)
@@ -317,7 +323,8 @@ def get(self, key: str) -> T | CacheMissSentinel:
         Note:
             Expired items are automatically deleted when accessed. This method does
             not raise exceptions for missing keys - use `CACHE_MISS` to check for
-            cache misses.
+            cache misses. Unlike mutating operations (`set`, `delete`, `clear`),
+            this method can be called even after the storage has been closed.
         """
         with self.__lock:
             value_obj = self._data.get(key)

atomic_lru/_storage/thread.py

@@ -64,6 +64,9 @@ def clean_func(start, stop):
     # Internal threading event used to signal thread termination
     _stop_event: threading.Event = field(default_factory=threading.Event)
 
+    # Internal lock to protect thread start/stop operations
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+
     # Internal thread instance
     _thread: threading.Thread | None = None
 
@@ -89,14 +92,15 @@ def start(self) -> None:
         automatically terminate when the main process exits (daemon thread).
 
         Note:
-            The thread is started as a daemon thread, meaning it will not prevent
-            the program from exiting if it's still running.
+            This method is thread-safe. The thread is started as a daemon thread,
+            meaning it will not prevent the program from exiting if it's still running.
         """
-        if self._thread is not None:
-            return
-        self._thread = threading.Thread(target=self.loop, daemon=True)
-        self._thread.start()
-        self._debug("Expiration thread started")
+        with self._lock:
+            if self._thread is not None:
+                return
+            self._thread = threading.Thread(target=self.loop, daemon=True)
+            self._thread.start()
+            self._debug("Expiration thread started")
 
     def stop(self, wait: bool = False) -> None:
         """Stop the expiration thread.
@@ -110,15 +114,17 @@ def stop(self, wait: bool = False) -> None:
                 False.
 
         Note:
-            When `wait=False`, the thread may continue running briefly after this
-            method returns. Use `wait=True` to ensure the thread has fully stopped
-            before proceeding.
+            This method is thread-safe. When `wait=False`, the thread may continue
+            running briefly after this method returns. Use `wait=True` to ensure the
+            thread has fully stopped before proceeding.
         """
-        if self._thread is None:
-            return
+        with self._lock:
+            if self._thread is None:
+                return
+            thread = self._thread
         self._stop_event.set()
         if wait:
-            self._thread.join()
+            thread.join()
             self._debug("Expiration thread stopped")
         else:
             self._debug("Stop event set for expiration thread")
@@ -135,7 +141,8 @@ def loop(self) -> None:
            items have been checked)
         4. Waits for `delay` seconds before the next iteration
 
-        The loop terminates when the stop event is set via `stop()`. If
+        The loop terminates when the stop event is set via `stop()`, or when the
+        storage is closed (indicated by RuntimeError from the callback). If
         `max_checks_per_iteration` is 0, no checks are performed but the loop
         continues to wait, allowing the thread to be stopped gracefully.
 
@@ -146,9 +153,14 @@ def loop(self) -> None:
         start_index: int = 0
         while not self._stop_event.is_set():
             if self.max_checks_per_iteration > 0:
-                tested, deleted = self.clean_callback(
-                    start_index, start_index + self.max_checks_per_iteration
-                )
+                try:
+                    tested, deleted = self.clean_callback(
+                        start_index, start_index + self.max_checks_per_iteration
+                    )
+                except RuntimeError:
+                    # Storage was closed while we were running - exit gracefully
+                    self._debug("Storage closed, expiration thread exiting")
+                    return
                 if tested == 0:
                     start_index = 0  # restart from the beginning
                 else:

docs/index.md

@@ -8,7 +8,7 @@
 
 ## Full API reference
 
-Refer to the [API reference](reference/api.md) for the full API.
+Refer to the [API reference](https://fabien-marty.github.io/atomic-lru/reference/api/) for the full API.
 
 {{ include_markdown('reference/dev.md', 1) }}