Add docs about the eviction policy to recipes

grantjenks · grantjenks · commit ee7a248e5c09 · 2023-04-10T22:37:39.000-07:00
diff --git a/diskcache/recipes.py b/diskcache/recipes.py
@@ -17,6 +17,9 @@ class Averager:
     Sometimes known as "online statistics," the running average maintains the
     total and count. The average can then be calculated at any time.
 
+    Assumes the key will not be evicted. Set the eviction policy to 'none' on
+    the cache to guarantee the key is not evicted.
+
     >>> import diskcache
     >>> cache = diskcache.FanoutCache()
     >>> ave = Averager(cache, 'latency')
@@ -65,6 +68,9 @@ def pop(self):
 class Lock:
     """Recipe for cross-process and cross-thread lock.
 
+    Assumes the key will not be evicted. Set the eviction policy to 'none' on
+    the cache to guarantee the key is not evicted.
+
     >>> import diskcache
     >>> cache = diskcache.Cache()
     >>> lock = Lock(cache, 'report-123')
@@ -113,6 +119,9 @@ def __exit__(self, *exc_info):
 class RLock:
     """Recipe for cross-process and cross-thread re-entrant lock.
 
+    Assumes the key will not be evicted. Set the eviction policy to 'none' on
+    the cache to guarantee the key is not evicted.
+
     >>> import diskcache
     >>> cache = diskcache.Cache()
     >>> rlock = RLock(cache, 'user-123')
@@ -181,6 +190,9 @@ def __exit__(self, *exc_info):
 class BoundedSemaphore:
     """Recipe for cross-process and cross-thread bounded semaphore.
 
+    Assumes the key will not be evicted. Set the eviction policy to 'none' on
+    the cache to guarantee the key is not evicted.
+
     >>> import diskcache
     >>> cache = diskcache.Cache()
     >>> semaphore = BoundedSemaphore(cache, 'max-cons', value=2)
@@ -251,6 +263,9 @@ def throttle(
 ):
     """Decorator to throttle calls to function.
 
+    Assumes keys will not be evicted. Set the eviction policy to 'none' on the
+    cache to guarantee the keys are not evicted.
+
     >>> import diskcache, time
     >>> cache = diskcache.Cache()
     >>> count = 0
@@ -305,6 +320,9 @@ def barrier(cache, lock_factory, name=None, expire=None, tag=None):
 
     Supports different kinds of locks: Lock, RLock, BoundedSemaphore.
 
+    Assumes keys will not be evicted. Set the eviction policy to 'none' on the
+    cache to guarantee the keys are not evicted.
+
     >>> import diskcache, time
     >>> cache = diskcache.Cache()
     >>> @barrier(cache, Lock)
