redis-allocator 0.0.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

redis_allocator/allocator.py

@@ -1,45 +1,40 @@
 """Redis-based distributed memory allocation system.
 
-This module provides the core functionality of the RedisAllocator system, 
+This module provides the core functionality of the RedisAllocator system,
 allowing for distributed memory allocation with support for garbage collection,
 thread health checking, and priority-based allocation mechanisms.
+
+Key features:
+1. Shared vs non-shared allocation modes:
+   - In shared mode, allocating an item simply removes it from the free list and puts it back to the tail
+   - In non-shared mode, allocation locks the item to prevent others from accessing it
+2. Garbage collection for stale/unhealthy items:
+   - Items that are locked (unhealthy) but in the free list are removed
+   - Items that are not in the free list but haven't been updated within their timeout are freed
+3. Soft binding mechanism:
+   - Maps object names to allocated keys for consistent allocation
+   - Prioritizes previously allocated keys when the same named object requests allocation
+4. Support for an updater to refresh the pool's keys periodically
+5. Policy-based control of allocation behavior through RedisAllocatorPolicy
 """
+import atexit
 import logging
 import weakref
+import contextlib
 from abc import ABC, abstractmethod
+from typing import Any, Callable
 from functools import cached_property
 from threading import current_thread
+from concurrent.futures import ThreadPoolExecutor
 from typing import (Optional, TypeVar, Generic,
                     Sequence, Iterable)
 from redis import StrictRedis as Redis
+from cachetools import cached, TTLCache
 from .lock import RedisLockPool, Timeout
 
 logger = logging.getLogger(__name__)
 
 
-class RedisAllocatableClass(ABC):
-    @abstractmethod
-    def set_config(self, key: str, params: dict):
-        """Set the configuration for the object.
-
-        Args:
-            key: The key to set the configuration for.
-            params: The parameters to set the configuration for.
-        """
-        pass
-
-    def close(self):
-        """close the object."""
-        pass
-
-    def name(self) -> Optional[str]:
-        """Get the cache name of the object."""
-        return None
-
-
-U = TypeVar('U', bound=RedisAllocatableClass)
-
-
 class RedisThreadHealthCheckPool(RedisLockPool):
     """A class that provides a simple interface for managing the health status of a thread.
 
@@ -84,14 +79,54 @@ class RedisThreadHealthCheckPool(RedisLockPool):
         self.unlock(self.current_thread_id)
 
 
+class RedisAllocatableClass(ABC):
+    """A class that can be allocated through RedisAllocator.
+
+    You should inherit from this class and implement the set_config method.
+    """
+
+    @abstractmethod
+    def set_config(self, key: str, params: dict):
+        """Set the configuration for the object.
+
+        Args:
+            key: The key to set the configuration for.
+            params: The parameters to set the configuration for.
+        """
+        pass
+
+    def open(self):
+        """Open the object."""
+        pass
+
+    def close(self):
+        """close the object."""
+        pass
+
+    def is_healthy(self):
+        return True
+
+    @property
+    def name(self) -> Optional[str]:
+        """Get the cache name of the object, if is none no soft binding will be used."""
+        return None
+
+    @property
+    def unique_id(self) -> str:
+        """Get the unique ID of the object."""
+        return ""
+
+
+U = TypeVar('U', bound=RedisAllocatableClass)
+
+
 class RedisAllocatorObject(Generic[U]):
     """Represents an object allocated through RedisAllocator.
 
     This class provides an interface for working with allocated objects
     including locking and unlocking mechanisms for thread-safe operations.
-
     """
-    _allocator: 'RedisAllocator'  # Reference to the allocator that created this object
+    allocator: 'RedisAllocator'  # Reference to the allocator that created this object
     key: str                      # Redis key for this allocated object
     params: Optional[dict]        # Parameters associated with this object
     obj: Optional[U]              # The actual object being allocated
@@ -105,7 +140,7 @@ class RedisAllocatorObject(Generic[U]):
             obj: The actual object being allocated
             params: Additional parameters passed by local program
         """
-        self._allocator = allocator
+        self.allocator = allocator
         self.key = key
         self.obj = obj
         self.params = params
@@ -119,47 +154,358 @@ class RedisAllocatorObject(Generic[U]):
             timeout: How long the lock should be valid (in seconds)
         """
         if timeout > 0:
-            self._allocator.update(self.key, timeout=timeout)
+            self.allocator.update(self.key, timeout=timeout)
         else:
-            self._allocator.free(self)
+            self.allocator.free(self)
+
+    def open(self):
+        """Open the object."""
+        if self.obj is not None:
+            self.obj.open()
 
     def close(self):
         """Kill the object."""
         if self.obj is not None:
             self.obj.close()
 
+    def is_healthy(self) -> bool:
+        """Check if the object is healthy."""
+        if self.obj is not None:
+            return self.obj.is_healthy()
+        return True
+
+    def set_unhealthy(self, duration: int = 3600):
+        """Set the object as unhealthy."""
+        if self.obj is not None and self.obj.name is not None:
+            self.allocator.unbind_soft_bind(self.obj.name)
+        self.allocator.update(self.key, timeout=duration)
+
+    def refresh(self, timeout: Timeout = 120):
+        """Refresh the object."""
+        self.close()
+        new_obj = self.allocator.policy.malloc(self.allocator, timeout=timeout,
+                                               obj=self.obj, params=self.params)
+        if new_obj is not None:
+            self.obj = new_obj.obj
+            self.key = new_obj.key
+            self.params = new_obj.params
+
+    @property
+    def unique_id(self) -> str:
+        """Get the unique ID of the object."""
+        if self.obj is None:
+            return self.key
+        return f"{self.key}:{self.obj.unique_id}"
+
+    @property
+    def name(self) -> Optional[str]:
+        """Get the name of the object."""
+        if self.obj is None:
+            return None
+        return self.obj.name
+
     def __del__(self):
         """Delete the object."""
         self.close()
 
 
+class RedisAllocatorUpdater:
+    """A class that updates the allocator keys."""
+
+    def __init__(self, params: Sequence[Any]):
+        """Initialize the allocator updater."""
+        assert len(params) > 0, "params should not be empty"
+        self.params = params
+        self.index = 0
+
+    @abstractmethod
+    def fetch(self, param: Any) -> Sequence[str]:
+        """Fetch the keys from params."""
+        pass
+
+    def __call__(self):
+        """Update the allocator key."""
+        current_param = self.params[self.index]
+        self.index = (self.index + 1) % len(self.params)
+        keys = self.fetch(current_param)
+        return keys
+
+    def __len__(self):
+        """Get the length of the allocator updater."""
+        return len(self.params)
+
+
+class RedisAllocatorPolicy(ABC):
+    """Abstract base class for Redis allocator policies.
+
+    This class defines the interface for allocation policies that can be used
+    with RedisAllocator to control allocation behavior.
+    """
+
+    def initialize(self, allocator: 'RedisAllocator'):
+        """Initialize the policy with an allocator instance.
+
+        Args:
+            allocator: The RedisAllocator instance to use with this policy
+        """
+        pass
+
+    @abstractmethod
+    def malloc(self, allocator: 'RedisAllocator', timeout: Timeout = 120,
+               obj: Optional[Any] = None, params: Optional[dict] = None,
+               cache_timeout: Timeout = 3600) -> Optional[RedisAllocatorObject]:
+        """Allocate a resource according to the policy.
+
+        Args:
+            allocator: The RedisAllocator instance
+            timeout: How long the allocation should be valid (in seconds)
+            obj: The object to associate with the allocation
+            params: Additional parameters for the allocation
+            cache_timeout: Timeout for the soft binding cache entry (seconds).
+                       Defaults to 3600.
+
+        Returns:
+            RedisAllocatorObject if allocation was successful, None otherwise
+        """
+        pass
+
+    @abstractmethod
+    def refresh_pool(self, allocator: 'RedisAllocator'):
+        """Refresh the allocation pool.
+
+        This method is called periodically to update the pool with new resources.
+
+        Args:
+            allocator: The RedisAllocator instance
+        """
+        pass
+
+    def check_health_once(self, r_obj: RedisAllocatorObject, duration: int = 3600) -> bool:
+        """Check the health of the object."""
+        with contextlib.closing(r_obj):
+            try:
+                if r_obj.is_healthy():
+                    return True
+                else:
+                    r_obj.set_unhealthy(duration)
+                    return False
+            except Exception as e:
+                logger.error(f"Error checking health of {r_obj.key}: {e}")
+                r_obj.set_unhealthy(duration)
+                raise
+
+    def check_health(self, allocator: 'RedisAllocator', lock_duration: Timeout = 3600, max_threads: int = 8,
+                     obj_fn: Optional[Callable[[str], Any]] = None,
+                     params_fn: Optional[Callable[[str], dict]] = None) -> tuple[int, int]:
+        """Check the health of the allocator.
+
+        Args:
+            allocator: The RedisAllocator instance
+            lock_duration: The duration of the lock (in seconds)
+            max_threads: The maximum number of threads to use
+
+        Returns:
+            A tuple containing the number of healthy and unhealthy items in the allocator
+        """
+        with ThreadPoolExecutor(max_workers=max_threads) as executor:
+            for key in allocator.keys():
+                if params_fn is not None:
+                    params = params_fn(key)
+                else:
+                    params = None
+                if obj_fn is not None:
+                    obj = obj_fn(key)
+                else:
+                    obj = None
+                alloc_obj = RedisAllocatorObject(allocator, key, obj, params)
+                executor.submit(self.check_health_once, alloc_obj, lock_duration)
+            executor.shutdown(wait=True)
+
+
+class DefaultRedisAllocatorPolicy(RedisAllocatorPolicy):
+    """Default implementation of RedisAllocatorPolicy.
+
+    This policy provides the following features:
+    1. Garbage collection before allocation: Automatically performs garbage collection
+       operations before allocating resources to ensure stale resources are reclaimed.
+
+    2. Soft binding prioritization: Prioritizes allocation of previously bound keys
+       for named objects, creating a consistent mapping between object names and keys.
+       If a soft binding exists but the bound key is no longer in the pool, the binding is
+       ignored and a new key is allocated.
+
+    3. Periodic pool updates: Uses an optional updater to refresh the pool's keys at
+       configurable intervals. Only one process/thread (the one that acquires the update lock)
+       will perform the update.
+
+    4. Configurable expiry times: Allows setting default expiry durations for pool items,
+       ensuring automatic cleanup of stale resources even without explicit garbage collection.
+
+    The policy controls when garbage collection happens, when the pool is refreshed with new keys,
+    and how allocation prioritizes resources.
+    """
+
+    def __init__(self, gc_count: int = 5, update_interval: int = 300,
+                 expiry_duration: int = -1, updater: Optional[RedisAllocatorUpdater] = None):
+        """Initialize the default allocation policy.
+
+        Args:
+            gc_count: Number of GC operations to perform before allocation
+            update_interval: Interval in seconds between pool updates
+            expiry_duration: Default timeout for pool items (-1 means no timeout)
+            updater: Optional updater for refreshing the pool's keys
+        """
+        self.gc_count = gc_count
+        self.update_interval: float = update_interval
+        self.expiry_duration: float = expiry_duration
+        self.updater = updater
+        self._allocator: Optional[weakref.ReferenceType['RedisAllocator']] = None
+        self._update_lock_key: Optional[str] = None
+        self.objects: weakref.WeakValueDictionary[str, RedisAllocatorObject] = weakref.WeakValueDictionary()
+
+    def initialize(self, allocator: 'RedisAllocator'):
+        """Initialize the policy with an allocator instance.
+
+        Args:
+            allocator: The RedisAllocator instance to use with this policy
+        """
+        self._allocator = weakref.ref(allocator)
+        self._update_lock_key = f"{allocator._pool_str()}|policy_update_lock"
+        atexit.register(lambda: self.finalize(self._allocator()))
+
+    def malloc(self, allocator: 'RedisAllocator', timeout: Timeout = 120,
+               obj: Optional[Any] = None, params: Optional[dict] = None,
+               cache_timeout: Timeout = 3600) -> Optional[RedisAllocatorObject]:
+        """Allocate a resource according to the policy.
+
+        This implementation:
+        1. Performs GC operations before allocation
+        2. Checks for soft binding based on object name
+        3. Falls back to regular allocation if no soft binding exists
+
+        Args:
+            allocator: The RedisAllocator instance
+            timeout: How long the allocation should be valid (in seconds)
+            obj: The object to associate with the allocation
+            params: Additional parameters for the allocation
+            cache_timeout: Timeout for the soft binding cache entry (seconds).
+                       Defaults to 3600.
+
+        Returns:
+            RedisAllocatorObject if allocation was successful, None otherwise
+        """
+        # Try to refresh the pool if necessary
+        self._try_refresh_pool(allocator)
+
+        # Perform GC operations before allocation
+        allocator.gc(self.gc_count)
+
+        # Fall back to regular allocation
+        # Explicitly call obj.name if obj exists
+        obj_name = obj.name if obj and hasattr(obj, 'name') and callable(
+            obj.name) else (obj.name if obj and hasattr(obj, 'name') else None)
+        key = allocator.malloc_key(timeout, obj_name,
+                                   cache_timeout=cache_timeout)
+        alloc_obj = RedisAllocatorObject(allocator, key, obj, params)
+        old_obj = self.objects.get(alloc_obj.unique_id, None)
+        if old_obj is not None:
+            old_obj.close()
+        self.objects[alloc_obj.unique_id] = alloc_obj
+        return alloc_obj
+
+    @cached(TTLCache(maxsize=64, ttl=5))
+    def _try_refresh_pool(self, allocator: 'RedisAllocator'):
+        """Try to refresh the pool if necessary and if we can acquire the lock.
+
+        Args:
+            allocator: The RedisAllocator instance
+        """
+        if self.updater is None:
+            return
+        if allocator.lock(self._update_lock_key, timeout=self.update_interval):
+            # If we got here, we acquired the lock, so we can update the pool
+            self.refresh_pool(allocator)
+
+    def refresh_pool(self, allocator: 'RedisAllocator'):
+        """Refresh the allocation pool using the updater.
+
+        Args:
+            allocator: The RedisAllocator instance
+        """
+        if self.updater is None:
+            return
+
+        keys = self.updater()
+
+        if len(keys) == 0:
+            logger.warning("No keys to update to the pool")
+            return
+
+        # Update the pool based on the number of keys
+        if len(self.updater) == 1:
+            allocator.assign(keys, timeout=self.expiry_duration)
+        else:
+            allocator.extend(keys, timeout=self.expiry_duration)
+
+    def finalize(self, allocator: 'RedisAllocator'):
+        """Finalize the policy."""
+        for obj in self.objects.values():
+            obj.close()
+
+
 class RedisAllocator(RedisLockPool, Generic[U]):
-    """A Redis-based distributed memory allocation system.
-    
-    This class implements a memory allocation interface using Redis as the backend store.
-    It manages a pool of resources that can be allocated, freed, and garbage collected.
-    The implementation uses a doubly-linked list structure stored in Redis hashes to
-    track available and allocated resources.
-    
-    Generic type U must implement the RedisContextableObject protocol, allowing
-    allocated objects to be used as context managers.
+    """A Redis-based distributed allocation system.
+
+    Manages a pool of resource identifiers (keys) using Redis, allowing distributed
+    clients to allocate, free, and manage these resources. It leverages Redis's
+    atomic operations via Lua scripts for safe concurrent access.
+
+    The allocator maintains a doubly-linked list in a Redis hash to track available
+    (free) resources. Allocated resources are tracked using standard Redis keys
+    that act as locks.
+
+    Key Concepts:
+    - Allocation Pool: A set of resource identifiers (keys) managed by the allocator.
+      Stored in a Redis hash (`<prefix>|<suffix>|pool`) representing a doubly-linked list.
+      Head/Tail pointers are stored in separate keys (`<prefix>|<suffix>|pool|head`,
+      `<prefix>|<suffix>|pool|tail`).
+    - Free List: The subset of keys within the pool that are currently available.
+      Represented by the linked list structure within the pool hash.
+    - Allocated State: A key is considered allocated if a corresponding lock key exists
+      (`<prefix>|<suffix>:<key>`).
+    - Shared Mode: If `shared=True`, allocating a key moves it to the tail of the
+      free list but does *not* create a lock key. This allows multiple clients to
+      "allocate" the same key concurrently, effectively using the list as a rotating pool.
+      If `shared=False` (default), allocation creates a lock key, granting exclusive access.
+    - Soft Binding: Allows associating a logical name with an allocated key. If an object
+      provides a `name`, the allocator tries to reuse the previously bound key for that name.
+      Stored in Redis keys like `<prefix>|<suffix>-cache:bind:<name>`.
+    - Garbage Collection (GC): Periodically scans the pool to reconcile the free list
+      with the lock states. Removes expired/locked items from the free list and returns
+      items whose locks have expired back to the free list.
+    - Policies: Uses `RedisAllocatorPolicy` (e.g., `DefaultRedisAllocatorPolicy`)
+      to customize allocation behavior, GC triggering, and pool updates.
+
+    Generic type U should implement `RedisAllocatableClass`.
     """
 
     def __init__(self, redis: Redis, prefix: str, suffix='allocator', eps=1e-6,
-                 shared=False):
-        """Initialize a RedisAllocator instance.
-        
+                 shared=False, policy: Optional[RedisAllocatorPolicy] = None):
+        """Initializes the RedisAllocator.
+
         Args:
-            redis: Redis client for communication with Redis server
-            prefix: Prefix for all Redis keys used by this allocator
-            suffix: Suffix for Redis keys to uniquely identify this allocator
-            eps: Small value for floating point comparisons
-            shared: Whether resources can be shared across multiple consumers
+            redis: StrictRedis client instance (must decode responses).
+            prefix: Prefix for all Redis keys used by this allocator instance.
+            suffix: Suffix to uniquely identify this allocator instance's keys.
+            eps: Small float tolerance for comparisons (used by underlying lock).
+            shared: If True, operates in shared mode (keys are rotated, not locked).
+                    If False (default), keys are locked upon allocation.
+            policy: Optional allocation policy. Defaults to `DefaultRedisAllocatorPolicy`.
         """
         super().__init__(redis, prefix, suffix=suffix, eps=eps)
         self.shared = shared
-        self.soft_bind_timeout = 3600  # Default timeout for soft bindings (1 hour)
-        self.objects: weakref.WeakValueDictionary[str, RedisAllocatorObject] = weakref.WeakValueDictionary()
+        self.policy = policy or DefaultRedisAllocatorPolicy()
+        self.policy.initialize(self)
 
     def object_key(self, key: str, obj: U):
         """Get the key for an object."""
@@ -169,38 +515,44 @@ class RedisAllocator(RedisLockPool, Generic[U]):
 
     def _pool_pointer_str(self, head: bool = True):
         """Get the Redis key for the head or tail pointer of the allocation pool.
-        
+
         Args:
             head: If True, get the head pointer key; otherwise, get the tail pointer key
-            
+
         Returns:
             String representation of the Redis key for the pointer
         """
         pointer_type = 'head' if head else 'tail'
         return f'{self._pool_str()}|{pointer_type}'
 
-    def _gc_cursor_str(self):
-        """Get the Redis key for the garbage collection cursor.
-        
-        Returns:
-            String representation of the Redis key for the GC cursor
-        """
-        return f'{self._pool_str()}|gc_cursor'
-
     @property
     def _lua_required_string(self):
-        """LUA script containing helper functions for Redis operations.
-        
-        This script defines various LUA functions for manipulating the doubly-linked list
-        structure that represents the allocation pool:
-        - pool_pointer_str: Get Redis keys for head/tail pointers
-        - gc_cursor_str: Get Redis key for GC cursor
-        - push_to_tail: Add an item to the tail of the linked list
-        - pop_from_head: Remove and return the item at the head of the linked list
-        - delete_item: Remove an item from anywhere in the linked list
+        """Base Lua script providing common functions for pool manipulation.
+
+        Includes functions inherited from RedisLockPool and adds allocator-specific ones:
+        - pool_pointer_str(head: bool): Returns the Redis key for the head/tail pointer.
+        - cache_str(): Returns the Redis key for the allocator's general cache.
+        - soft_bind_name(name: str): Returns the Redis key for a specific soft binding.
+        - split_pool_value(value: str): Parses the 'prev||next||expiry' string stored
+                                        in the pool hash for a key.
+        - join_pool_value(prev: str, next: str, expiry: int): Creates the value string.
+        - timeout_to_expiry(timeout: int): Converts relative seconds to absolute Unix timestamp.
+        - is_expiry_invalid(expiry: int): Checks if an absolute expiry time is in the past.
+        - is_expired(value: str): Checks if a pool item's expiry is in the past.
+        - push_to_tail(itemName: str, expiry: int): Adds/updates an item at the tail of the free list.
+        - pop_from_head(): Removes and returns the item from the head of the free list,
+                           skipping expired or locked items. Returns (nil, -1) if empty.
+        - set_item_allocated(itemName: str): Removes an item from the free list structure.
+        - check_item_health(itemName: str, value: str|nil): Core GC logic for a single item.
+            - If item is marked #ALLOCATED but has no lock -> push to tail (return to free list).
+            - If item is in free list but expired -> remove from pool hash.
+            - If item is in free list but locked -> mark as #ALLOCATED (remove from free list).
         """
         return f'''
         {super()._lua_required_string}
+        local function time()
+            return tonumber(redis.call("TIME")[1])
+        end
         local function pool_pointer_str(head)
             local pointer_type = 'head'
             if not head then
@@ -208,185 +560,265 @@ class RedisAllocator(RedisLockPool, Generic[U]):
             end
             return '{self._pool_str()}|' .. pointer_type
         end
-        local function gc_cursor_str()
-            return '{self._pool_str()}|gc_cursor'
+        local function cache_str()
+            return '{self._cache_str}'
+        end
+        local function soft_bind_name(name)
+            if name == "" or not name then
+                return ""
+            end
+            return cache_str() .. ':bind:' .. name
+        end
+        local function split_pool_value(value)
+            if not value or value == "" then
+                return "", "", -1
+            end
+            value = tostring(value)
+            local prev, next, expiry = string.match(value, "(.*)||(.*)||(.*)")
+            return prev, next, tonumber(expiry)
+        end
+        local function join_pool_value(prev, next, expiry)
+            if expiry == nil then
+                expiry = -1
+            end
+            return tostring(prev) .. "||" .. tostring(next) .. "||" .. tostring(expiry)
+        end
+        local function timeout_to_expiry(timeout)
+            if timeout == nil or timeout <= 0 then
+                return -1
+            end
+            return time() + timeout
+        end
+        local function is_expiry_invalid(expiry)
+            return expiry ~= nil and expiry > 0 and expiry <= time()
+        end
+        local function is_expired(value)
+            local _, _, expiry = split_pool_value(value)
+            return is_expiry_invalid(expiry)
         end
         local poolItemsKey = pool_str()
         local headKey      = pool_pointer_str(true)
         local tailKey      = pool_pointer_str(false)
-        local function push_to_tail(itemName)
-            local tail         = redis.call("GET", tailKey)
+        local function push_to_tail(itemName, expiry)  -- push the item to the free list
+            local tail = redis.call("GET", tailKey)
             if not tail then
                 tail = ""
             end
-            redis.call("HSET", poolItemsKey, itemName, tostring(tail) .. "||")
-            if tail == "" then
+            redis.call("HSET", poolItemsKey, itemName, join_pool_value(tail, "", expiry))
+            if tail == "" then  -- the free list is empty chain
                 redis.call("SET", headKey, itemName)
             else
                 local tailVal = redis.call("HGET", poolItemsKey, tail)
-                local prev, _ = string.match(tailVal, "(.*)||(.*)")
-                redis.call("HSET", poolItemsKey, tail, tostring(prev) .. "||" .. tostring(itemName))
+                local prev, next, expiry = split_pool_value(tailVal)
+                assert(next == "", "tail is not the last item in the free list")
+                redis.call("HSET", poolItemsKey, tail, join_pool_value(prev, itemName, expiry))
             end
-            redis.call("SET", tailKey, itemName)
+            redis.call("SET", tailKey, itemName)  -- set the tail point to the new item
         end
-        local function pop_from_head()
+        local function pop_from_head()  -- pop the item from the free list
             local head = redis.call("GET", headKey)
-            if head == nil or head == "" then
-                return nil
+            if not head or head == "" then  -- the free list is empty
+                return nil, -1
             end
             local headVal = redis.call("HGET", poolItemsKey, head)
-            if headVal == nil then
-                redis.call("SET", headKey, "")
-                redis.call("SET", tailKey, "")
-                return nil
-            else
-                assert(headVal ~= "#ALLOCATED", "head is allocated")
+            assert(headVal ~= nil, "head should not nil")
+            local headPrev, headNext, headExpiry = split_pool_value(headVal)
+            -- Check if the head item has expired or is locked
+            if is_expiry_invalid(headExpiry) then  -- the item has expired
+                redis.call("HDEL", poolItemsKey, head)
+                redis.call("SET", headKey, headNext)
+                return pop_from_head()
             end
-            local _, next = string.match(headVal, "(.*)||(.*)")
-            if next == "" then
+            if redis.call("EXISTS", key_str(head)) > 0 then  -- the item is locked
+                redis.call("HSET", poolItemsKey, head, join_pool_value("#ALLOCATED", "#ALLOCATED", headExpiry))
+                redis.call("SET", headKey, headNext)
+                return pop_from_head()
+            end
+            local prev, next, expiry = split_pool_value(headVal)
+            if next == "" then  -- the item is the last in the free list
                 redis.call("SET", headKey, "")
                 redis.call("SET", tailKey, "")
             else
                 local nextVal = redis.call("HGET", poolItemsKey, next)
-                local prev, _ = string.match(nextVal, "(.*)||(.*)")
-                redis.call("HSET", poolItemsKey, next, tostring("") .. "||" .. tostring(prev))
+                local nextPrev, nextNext, nextExpiry = split_pool_value(nextVal)
+                redis.call("HSET", poolItemsKey, next, join_pool_value("", nextNext, nextExpiry))
                 redis.call("SET", headKey, next)
             end
-            return head
+            redis.call("HSET", poolItemsKey, head, join_pool_value("#ALLOCATED", "#ALLOCATED", expiry))
+            return head, headExpiry
         end
-        local function delete_item(itemName)
-            local val = redis.call("HGET", poolItemsKey, itemName)
-            if val ~= '#ALLOCATED' then
-                local prev, next = string.match(val, "(.*)||(.*)")
-                if prev ~= "" then
-                    local prevVal = redis.call("HGET", poolItemsKey, prev)
-                    if prevVal then
-                        local p, _ = string.match(prevVal, "(.*)||(.*)")
-                        redis.call("HSET", poolItemsKey, prev, tostring(p) .. "||" .. tostring(next))
+        local function set_item_allocated(itemName, val)
+            if not val then
+                val = redis.call("HGET", poolItemsKey, itemName)
+            end
+            if val then
+                local prev, next, expiry = split_pool_value(val)
+                if prev ~= "#ALLOCATED" then
+                    if is_expiry_invalid(expiry) then
+                        redis.call("HDEL", poolItemsKey, itemName)
                     end
-                else
-                    redis.call("SET", headKey, next or "")
-                end
-                if next ~= "" then
-                    local nxtVal = redis.call("HGET", poolItemsKey, next)
-                    if nxtVal then
-                        local _, n = string.match(nxtVal, "(.*)||(.*)")
-                        redis.call("HSET", poolItemsKey, next, tostring(prev) .. "||" .. tostring(n))
+                    if prev ~= "" then
+                        local prevVal = redis.call("HGET", poolItemsKey, prev)
+                        if prevVal then
+                            local prevPrev, prevNext, prevExpiry = split_pool_value(prevVal)
+                            redis.call("HSET", poolItemsKey, prev, join_pool_value(prevPrev, next, prevExpiry))
+                        end
+                    else
+                        redis.call("SET", headKey, next or "")
                     end
-                else
-                    redis.call("SET", tailKey, prev or "")
+                    if next ~= "" then
+                        local nextVal = redis.call("HGET", poolItemsKey, next)
+                        if nextVal then
+                            local nextPrev, nextNext, nextExpiry = split_pool_value(nextVal)
+                            redis.call("HSET", poolItemsKey, next, join_pool_value(prev, nextNext, nextExpiry))
+                        end
+                    else
+                        redis.call("SET", tailKey, prev or "")
+                    end
+                    redis.call("HSET", poolItemsKey, itemName, join_pool_value("#ALLOCATED", "#ALLOCATED", expiry))
                 end
             end
-            redis.call("HDEL", poolItemsKey, itemName)
         end
-        '''
-
-    @property
-    def _extend_lua_string(self):
-        """LUA script for extending the allocation pool with new resources.
-        
-        This script adds new items to the pool if they don't already exist.
-        New items are added to the tail of the linked list.
-        """
-        return f'''{self._lua_required_string}
-        for _, itemName in ipairs(ARGV) do
-            if redis.call("HEXISTS", poolItemsKey, itemName) == 1 then
-                -- todo: gc check
+        local function check_item_health(itemName, value)
+            if not value then
+                value = redis.call("HGET", pool_str(), itemName)
+            end
+            assert(value, "value should not be nil")
+            local prev, next, expiry = split_pool_value(value)
+            if is_expiry_invalid(expiry) then  -- Check if the item has expired
+                set_item_allocated(itemName)
+                redis.call("HDEL", poolItemsKey, itemName)
+            end
+            local locked = redis.call("EXISTS", key_str(itemName)) > 0
+            if prev == "#ALLOCATED" then
+                if not locked then
+                    push_to_tail(itemName, expiry)
+                end
             else
-                push_to_tail(itemName)
+                if locked then
+                    set_item_allocated(itemName)
+                end
             end
         end
         '''
 
     @cached_property
     def _extend_script(self):
-        """Cached Redis script for extending the allocation pool."""
-        return self.redis.register_script(self._extend_lua_string)
+        """Cached Lua script to add or update keys in the pool.
+
+        Iterates through provided keys (ARGV[2...]).
+        If a key doesn't exist in the pool hash, it's added to the tail of the free list
+        using push_to_tail() with the specified expiry (calculated from ARGV[1] timeout).
+        If a key *does* exist, its expiry time is updated in the pool hash.
+        """
+        return self.redis.register_script(f'''
+        {self._lua_required_string}
+        local timeout = tonumber(ARGV[1] or -1)
+        local expiry = timeout_to_expiry(timeout)
+        for i=2, #ARGV do
+            local itemName = ARGV[i]
+            local val = redis.call("HGET", poolItemsKey, itemName)
+            if val then  -- only refresh the expiry timeout
+                local prev, next, _ = split_pool_value(val)
+                val = join_pool_value(prev, next, expiry)
+                redis.call("HSET", poolItemsKey, itemName, val)
+            else -- refresh the expiry timeout
+                push_to_tail(itemName, expiry)
+            end
+        end''')
 
-    def extend(self, keys: Optional[Sequence[str]] = None):
+    def extend(self, keys: Optional[Sequence[str]] = None, timeout: int = -1):
         """Add new resources to the allocation pool.
-        
+
         Args:
             keys: Sequence of resource identifiers to add to the pool
+            timeout: Optional timeout in seconds for the pool items (-1 means no timeout)
         """
         if keys is not None and len(keys) > 0:
-            self._extend_script(args=keys)
-
-    @property
-    def _shrink_lua_string(self):
-        """LUA script for removing resources from the allocation pool.
-        
-        This script removes specified items from the pool by deleting them
-        from the linked list structure.
-        """
-        return f'''{self._lua_required_string}
-        for _, itemName in ipairs(ARGV) do
-            delete_item(itemName)
-        end
-        '''
+            # Ensure timeout is integer for Lua script
+            int_timeout = timeout if timeout is not None else -1
+            self._extend_script(args=[int_timeout] + list(keys))
 
     @cached_property
     def _shrink_script(self):
-        """Cached Redis script for shrinking the allocation pool."""
-        return self.redis.register_script(self._shrink_lua_string)
+        """Cached Lua script to remove keys from the pool.
+
+        Iterates through provided keys (ARGV[1...]).
+        For each key:
+        1. Calls set_item_allocated() to remove it from the free list structure.
+        2. Deletes the key entirely from the pool hash using HDEL.
+        """
+        return self.redis.register_script(f'''{self._lua_required_string}
+        for i=1, #ARGV do
+            local itemName = ARGV[i]
+            set_item_allocated(itemName)
+            redis.call("HDEL", poolItemsKey, itemName)
+        end''')
 
     def shrink(self, keys: Optional[Sequence[str]] = None):
         """Remove resources from the allocation pool.
-        
+
         Args:
             keys: Sequence of resource identifiers to remove from the pool
         """
         if keys is not None and len(keys) > 0:
             self._shrink_script(args=keys)
 
-    @property
-    def _assign_lua_string(self):
-        """LUA script for completely replacing the resources in the allocation pool.
-        
-        This script clears the existing pool and replaces it with a new set of resources.
-        Items not in the new set are removed, and items in the new set but not in the
-        existing pool are added to the tail of the linked list.
-        """
-        return f'''{self._lua_required_string}
-        local wantSet  = {{}}
-        for _, k in ipairs(ARGV) do
-            wantSet[k] = true
+    @cached_property
+    def _assign_script(self):
+        """Cached Lua script to set the pool to exactly the given keys.
+
+        1. Builds a Lua set (`assignSet`) of the desired keys (ARGV[2...]).
+        2. Fetches all current keys from the pool hash (HKEYS).
+        3. Iterates through current keys:
+           - If a key is *not* in `assignSet`, it's removed from the pool
+             (set_item_allocated() then HDEL).
+           - If a key *is* in `assignSet`, it's marked as processed by setting
+             `assignSet[key] = nil`.
+        4. Iterates through the remaining keys in `assignSet` (those not already
+           in the pool). These are added to the tail of the free list using
+           push_to_tail() with the specified expiry (from ARGV[1] timeout).
+        """
+        return self.redis.register_script(f'''{self._lua_required_string}
+        local timeout = tonumber(ARGV[1] or -1)
+        local expiry = timeout_to_expiry(timeout)
+        local assignSet  = {{}}
+        for i=2, #ARGV do
+            local k = ARGV[i]
+            assignSet[k] = true
         end
         local allItems = redis.call("HKEYS", poolItemsKey)
         for _, itemName in ipairs(allItems) do
-            if not wantSet[itemName] then
-                delete_item(itemName)
+            if not assignSet[itemName] then
+                set_item_allocated(itemName)
+                redis.call("HDEL", poolItemsKey, itemName)
             else
-                wantSet[itemName] = nil
+                assignSet[itemName] = nil
             end
         end
-        for k, v in pairs(wantSet) do
+        for k, v in pairs(assignSet) do
             if v then
-                push_to_tail(k)
+                push_to_tail(k, expiry)
             end
         end
-        '''
+        ''')
 
-    @cached_property
-    def _assign_lua_script(self):
-        """Cached Redis script for assigning resources to the allocation pool."""
-        return self.redis.register_script(self._assign_lua_string)
-
-    def assign(self, keys: Optional[Sequence[str]] = None):
+    def assign(self, keys: Optional[Sequence[str]] = None, timeout: int = -1):
         """Completely replace the resources in the allocation pool.
-        
+
         Args:
             keys: Sequence of resource identifiers to assign to the pool,
                  replacing any existing resources
+            timeout: Optional timeout in seconds for the pool items (-1 means no timeout)
         """
         if keys is not None and len(keys) > 0:
-            self._assign_lua_script(args=keys)
+            self._assign_script(args=[timeout] + list(keys))
         else:
             self.clear()
 
     def keys(self) -> Iterable[str]:
         """Get all resource identifiers in the allocation pool.
-        
+
         Returns:
             Iterable of resource identifiers in the pool
         """
@@ -394,10 +826,10 @@ class RedisAllocator(RedisLockPool, Generic[U]):
 
     def __contains__(self, key):
         """Check if a resource identifier is in the allocation pool.
-        
+
         Args:
             key: Resource identifier to check
-            
+
         Returns:
             True if the resource is in the pool, False otherwise
         """
@@ -406,7 +838,7 @@ class RedisAllocator(RedisLockPool, Generic[U]):
     @property
     def _cache_str(self):
         """Get the Redis key for the allocator's cache.
-        
+
         Returns:
             String representation of the Redis key for the cache
         """
@@ -419,180 +851,287 @@ class RedisAllocator(RedisLockPool, Generic[U]):
 
     def _soft_bind_name(self, name: str) -> str:
         """Get the Redis key for a soft binding.
-        
+
         Args:
             name: Name of the soft binding
-            
+
         Returns:
             String representation of the Redis key for the soft binding
         """
         return f"{self._cache_str}:bind:{name}"
 
-    def update_soft_bind(self, name: str, key: str):
+    def update_soft_bind(self, name: str, key: str, timeout: Timeout = 3600):
         """Update a soft binding between a name and a resource.
-        
+
+        Soft bindings create a persistent mapping between named objects and allocated keys,
+        allowing the same key to be consistently allocated to the same named object.
+        This is useful for maintaining affinity between objects and their resources.
+
         Args:
             name: Name to bind
             key: Resource identifier to bind to the name
         """
-        self.update(self._soft_bind_name(name), key, timeout=self.soft_bind_timeout)
+        self.update(self._soft_bind_name(name), key, timeout=timeout)
 
     def unbind_soft_bind(self, name: str):
         """Remove a soft binding.
-        
+
+        This removes the persistent mapping between a named object and its allocated key,
+        allowing the key to be freely allocated to any requestor.
+
         Args:
             name: Name of the soft binding to remove
         """
         self.unlock(self._soft_bind_name(name))
 
-    @property
-    def _malloc_lua_script(self):
-        """LUA script for allocating a resource from the pool.
-        
-        This script allocates a resource by popping an item from the head
-        of the linked list and marking it as allocated. If the allocator
-        is not shared, the script also sets a lock on the allocated resource.
+    def get_soft_bind(self, name: str) -> Optional[str]:
+        """Get the resource identifier bound to a name.
+
+        Args:
+            name: Name of the soft binding
         """
-        return f'''
+        return self.redis.get(self._soft_bind_name(name))
+
+    @cached_property
+    def _malloc_script(self):
+        """Cached Lua script to allocate a key from the pool.
+
+        Input ARGS: timeout, name (for soft binding), soft_bind_timeout
+
+        1. Soft Binding Check (if name provided):
+           - Tries to GET the bound key from the soft bind cache key.
+           - If found and the key is *not* currently locked (checked via EXISTS key_str(cachedKey)),
+             it refreshes the soft bind expiry and returns the cached key.
+           - If found but the key *is* locked, it deletes the stale soft bind entry.
+        2. Pop from Head: Calls `pop_from_head()` to get the next available key
+           from the free list head. This function internally skips expired/locked items.
+        3. Lock/Update (if key found):
+           - If `shared=False`: Sets the lock key (`key_str(itemName)`) with the specified timeout.
+           - If `shared=True`: Calls `push_to_tail()` to put the item back onto the free list immediately.
+        4. Update Soft Bind Cache (if key found and name provided):
+           - Sets the soft bind cache key to the allocated `itemName` with its timeout.
+        5. Returns the allocated `itemName` or nil if the pool was empty.
+        """
+        return self.redis.register_script(f'''
         {self._lua_required_string}
         local shared = {1 if self.shared else 0}
+
         local timeout = tonumber(ARGV[1])
-        local itemName = pop_from_head()
-        if itemName ~= nil then
-            if redis.call("EXISTS", key_str(itemName)) == 1 then
-                itemName = nil
-            else
-                if not shared then
-                    if timeout ~= nil then
-                        redis.call("SET", key_str(itemName), "1", "EX", timeout)
-                    else
-                        redis.call("SET", key_str(itemName), "1")
+        local name_arg = ARGV[2] -- Original name argument
+        local cacheName = soft_bind_name(name_arg) -- Key for soft binding cache
+        local cacheTimeout = tonumber(ARGV[3]) -- Timeout for the soft binding cache entry
+        local function refresh_cache(cacheKey)
+            -- Only refresh if a valid name and timeout were provided
+            if name_arg ~= "" then
+                if cacheTimeout ~= nil and cacheTimeout > 0 then
+                    redis.call("SET", cacheName, cacheKey, "EX", cacheTimeout)
+                else -- If timeout is invalid/zero, set without expiry
+                    redis.call("SET", cacheName, cacheKey)
+                end
+            end
+        end
+        -- Check soft binding only if a name was provided
+        if name_arg ~= "" then
+            local cachedKey = redis.call("GET", cacheName)
+            if cachedKey then
+                -- Check if the cached key exists and is currently locked (in non-shared mode)
+                if redis.call("HEXISTS", poolItemsKey, cachedKey) <= 0 or redis.call("EXISTS", key_str(cachedKey)) > 0 then
+                    -- Cached key is locked, binding is stale, remove it
+                    redis.call("DEL", cacheName)
+                else
+                    -- Cached key is valid (either not locked or in shared mode)
+                    refresh_cache(cachedKey) -- Refresh the cache expiry
+                    if shared == 0 then
+                        redis.call("SET", key_str(cachedKey), "1", "EX", timeout)
+                        set_item_allocated(cachedKey)
                     end
+                    return cachedKey
                 end
             end
         end
-        return itemName
-        '''
 
-    @cached_property
-    def _malloc_script(self):
-        """Cached Redis script for allocating a resource."""
-        return self.redis.register_script(self._malloc_lua_script)
+        -- No valid soft bind found, proceed with normal allocation
+        local itemName, expiry = pop_from_head()
+        if itemName ~= nil then
+            if shared == 0 then
+                -- Non-shared mode: Acquire lock
+                if timeout ~= nil and timeout > 0 then
+                    redis.call("SET", key_str(itemName), "1", "EX", timeout)
+                else
+                    redis.call("SET", key_str(itemName), "1") -- Set without expiry if timeout <= 0
+                end
+            else
+                -- Shared mode: Just put it back to the tail
+                push_to_tail(itemName, expiry)
+            end
+        end
 
-    def malloc_key(self, timeout: Timeout = 120) -> Optional[str]:
+        -- If allocation was successful and a name was provided, update the soft bind cache
+        if itemName then
+            refresh_cache(itemName)
+        end
+        return itemName
+        ''')
+
+    def malloc_key(self, timeout: Timeout = 120, name: Optional[str] = None,
+                   cache_timeout: Timeout = 3600) -> Optional[str]:
         """Allocate a resource key from the pool.
-        
+
+        The behavior depends on the allocator's shared mode:
+        - In non-shared mode (default): Locks the allocated key for exclusive access
+        - In shared mode: Simply removes the key from the free list without locking it
+
         Args:
-            timeout: How long the allocation should be valid (in seconds)
-            
+            timeout: How long the allocation lock should be valid (in seconds).
+            name: Optional name to use for soft binding.
+            cache_timeout: Timeout for the soft binding cache entry (seconds).
+                           Defaults to 3600. If <= 0, cache entry persists indefinitely.
+
         Returns:
             Resource identifier if allocation was successful, None otherwise
         """
-        return self._malloc_script(keys=[self._to_seconds(timeout)])
+        if name is None:
+            name = ""
+        # Convert timeout values to integers for Lua
+        lock_timeout_sec = int(self._to_seconds(timeout))
+        cache_timeout_sec = int(self._to_seconds(cache_timeout))
+        # Convert integers to strings for Lua script arguments
+        return self._malloc_script(args=[
+            lock_timeout_sec,
+            name,
+            cache_timeout_sec,
+        ])
 
-    def malloc(self, timeout: Timeout = 120, obj: Optional[U] = None, params: Optional[dict] = None) -> Optional[RedisAllocatorObject[U]]:
+    def malloc(self, timeout: Timeout = 120, obj: Optional[U] = None, params: Optional[dict] = None,
+               cache_timeout: Timeout = 3600) -> Optional[RedisAllocatorObject[U]]:
         """Allocate a resource from the pool and wrap it in a RedisAllocatorObject.
-        
+
+        If a policy is configured, it will be used to control the allocation behavior.
+        Otherwise, the basic allocation mechanism will be used.
+
         Args:
-            timeout: How long the allocation should be valid (in seconds)
-            obj: The object to wrap in the RedisAllocatorObject
-            params: Additional parameters to associate with the allocated object
-            
+            timeout: How long the allocation lock should be valid (in seconds)
+            obj: The object to wrap in the RedisAllocatorObject. If it has a `.name`,
+                 soft binding will be attempted.
+            params: Additional parameters to associate with the allocated object.
+            cache_timeout: Timeout for the soft binding cache entry (seconds).
+                           Defaults to 3600. Passed to the policy or `malloc_key`.
+
         Returns:
             RedisAllocatorObject wrapping the allocated resource if successful, None otherwise
         """
-        key = self.malloc_key(timeout)
-        if key is None:
-            return None
-        return RedisAllocatorObject(self, key, obj, params)
+        if self.policy:
+            # Pass cache_timeout to the policy's malloc method
+            return self.policy.malloc(
+                self, timeout, obj, params,
+                cache_timeout=cache_timeout
+            )
+        # No policy, call malloc_key directly
+        # Explicitly call obj.name if obj exists
+        name = obj.name if obj and hasattr(obj, 'name') else None
+        key = self.malloc_key(timeout, name, cache_timeout=cache_timeout)
+        return RedisAllocatorObject(
+            self, key, obj, params
+        )
 
-    @property
-    def _free_lua_script(self):
-        """LUA script for freeing allocated resources.
-        
-        This script frees allocated resources by removing their locks
-        and pushing them back to the tail of the linked list.
+    @cached_property
+    def _free_script(self):
+        """Cached Lua script to free allocated keys.
+
+        Iterates through provided keys (ARGV[2...]).
+        For each key:
+        1. Deletes the corresponding lock key (`key_str(k)`) using DEL.
+           If the key existed (DEL returns 1), it proceeds.
+        2. Adds the key back to the tail of the free list using `push_to_tail()`
+           with the specified expiry (calculated from ARGV[1] timeout).
         """
-        return f'''
+        return self.redis.register_script(f'''
         {self._lua_required_string}
-        for _, k in ipairs(KEYS) do
-            redis.call('DEL', key_str(k))
-            push_to_tail(k)
+        local timeout = tonumber(ARGV[1] or -1)
+        local expiry = timeout_to_expiry(timeout)
+        for i=2, #ARGV do
+            local k = ARGV[i]
+            local deleted = redis.call('DEL', key_str(k))
+            if deleted > 0 then -- Only push back to pool if it was actually locked/deleted
+                push_to_tail(k, expiry)
+            end
         end
-        '''
+        ''')
 
-    @cached_property
-    def _free_script(self):
-        """Cached Redis script for freeing allocated resources."""
-        return self.redis.register_script(self._free_lua_script)
-
-    def free_keys(self, *keys: str):
+    def free_keys(self, *keys: str, timeout: int = -1):
         """Free allocated resources.
-        
+
         Args:
             *keys: Resource identifiers to free
+            timeout: Optional timeout in seconds for the pool items (-1 means no timeout)
         """
-        self._free_script(keys, args=keys)
+        if keys:
+            self._free_script(args=[timeout] + list(keys))
+
+    def free(self, obj: RedisAllocatorObject[U], timeout: int = -1):
+        """Free an allocated object.
 
-    def free(self, obj: RedisAllocatorObject[U]):
-        """Free an allocated object."""
-        self.free_keys(obj.key)
+        Args:
+            obj: The allocated object to free
+            timeout: Optional timeout in seconds for the pool item (-1 means no timeout)
+        """
+        self.free_keys(obj.key, timeout=timeout)
+
+    def _gc_cursor_str(self):
+        """Get the Redis key for the garbage collection cursor.
+
+        Returns:
+            String representation of the Redis key for the GC cursor
+        """
+        return f'{self._pool_str()}|gc_cursor'
 
     @cached_property
     def _gc_script(self):
-        """Cached Redis script for garbage collection."""
-        return self.redis.register_script(self._gc_lua_script)
+        """Cached Lua script for performing garbage collection.
 
-    @property
-    def _gc_lua_script(self):
-        """LUA script for garbage collection of the allocation pool.
-        
-        This script scans through the pool and performs two types of cleanup:
-        1. Resources marked as allocated but not actually locked are pushed back
-           to the available pool
-        2. Resources not marked as allocated but actually locked are marked as allocated
-        
-        This ensures consistency between the allocation metadata and the actual locks.
+        Uses HSCAN to iterate through the pool hash incrementally.
+        Input ARGS: count (max items to scan per call)
+
+        1. Gets the scan cursor from a dedicated key (`_gc_cursor_str()`).
+        2. Calls HSCAN on the pool hash (`pool_str()`) starting from the cursor,
+           requesting up to `count` items.
+        3. Iterates through the key-value pairs returned by HSCAN.
+        4. For each item, calls `check_item_health()` to reconcile its state
+           (see `_lua_required_string` documentation).
+        5. Saves the new cursor returned by HSCAN for the next GC call.
         """
-        return f'''
+        return self.redis.register_script(f'''
         {self._lua_required_string}
-        local n = tonumber(ARGV[1])
-        local cursorKey = gc_cursor_str()
-        local oldCursor = redis.call("GET", cursorKey)
-        if not oldCursor or oldCursor == "" then
-            oldCursor = "0"
+        local cursorKey = '{self._gc_cursor_str()}'
+        local function get_cursor()
+            local oldCursor = redis.call("GET", cursorKey)
+            if not oldCursor or oldCursor == "" then
+                return "0"
+            else
+                return oldCursor
+            end
+        end
+        local function set_cursor(cursor)
+            redis.call("SET", cursorKey, cursor)
         end
-        local scanResult = redis.call("HSCAN", poolItemsKey, oldCursor, "COUNT", n)
+        local n = tonumber(ARGV[1])
+        local scanResult = redis.call("HSCAN", pool_str(), get_cursor(), "COUNT", n)
         local newCursor  = scanResult[1]
         local kvList     = scanResult[2]
-        local tail       = redis.call("GET", tailKey)
-        if not tail then
-            tail = ""
-        end
         for i = 1, #kvList, 2 do
             local itemName = kvList[i]
             local val      = kvList[i + 1]
-            if val == "#ALLOCATED" then
-                local locked = (redis.call("EXISTS", key_str(itemName)) == 1)
-                if not locked then
-                    push_to_tail(itemName)
-                end
-            else
-                local locked = (redis.call("EXISTS", key_str(itemName)) == 1)
-                if locked then
-                    delete_item(itemName)
-                    redis.call("HSET", poolItemsKey, itemName, "#ALLOCATED")
-                end
-            end
+            check_item_health(itemName, val)
         end
-        '''
+        set_cursor(newCursor)
+        ''')
 
     def gc(self, count: int = 10):
         """Perform garbage collection on the allocation pool.
-        
+
         This method scans through the pool and ensures consistency between
         the allocation metadata and the actual locks.
-        
+
         Args:
             count: Number of items to check in this garbage collection pass
         """