docs: add warnings

Author: phi-friday

src/typed_diskcache/implement/sync/lock.py

@@ -252,6 +252,12 @@ def release(self) -> None:
 class AsyncLock(AsyncLockProtocol):
     """Lock implementation using spin-lock algorithm.
 
+    !!! warning
+        If the current Python interpreter is free-threading (without GIL),
+        using [`AsyncLock`][typed_diskcache.AsyncLock] may lead to unexpected
+        behavior. Consider using [`SyncLock`][typed_diskcache.SyncLock]
+        instead in such cases.
+
     Assumes the key will not be evicted. Set the eviction policy to 'none' on
     the cache to guarantee the key is not evicted.
 
@@ -376,6 +382,12 @@ async def __aexit__(
 class AsyncRLock(AsyncLock):
     """Re-entrant lock implementation using spin-lock algorithm.
 
+    !!! warning
+        If the current Python interpreter is free-threading (without GIL),
+        using [`AsyncRLock`][typed_diskcache.AsyncRLock] may lead to unexpected
+        behavior. Consider using [`SyncRLock`][typed_diskcache.SyncRLock]
+        instead in such cases.
+
     Assumes the key will not be evicted. Set the eviction policy to 'none' on
     the cache to guarantee the key is not evicted.
 

src/typed_diskcache/implement/sync/semaphore.py

@@ -179,6 +179,12 @@ def __exit__(
 class AsyncSemaphore(AsyncSemaphoreProtocol):
     """Asynchronous semaphore implementation using spin-lock algorithm.
 
+    !!! warning
+        If the current Python interpreter is free-threading (without GIL),
+        using [`AsyncSemaphore`][typed_diskcache.AsyncSemaphore] may lead to unexpected
+        behavior. Consider using [`SyncSemaphore`][typed_diskcache.SyncSemaphore]
+        instead in such cases.
+
     Assumes the key will not be evicted. Set the eviction policy to 'none' on
     the cache to guarantee the key is not evicted.