redis-allocator 0.6.1__tar.gz → 0.7.0__tar.gz

{redis_allocator-0.6.1/redis_allocator.egg-info → redis_allocator-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-allocator
-Version: 0.6.1
+Version: 0.7.0
 Summary: Redis-based resource allocation system.
 Home-page: https://github.com/invoker-bot/RedisAllocator-python
 Author: Invoker Bot
@@ -25,7 +25,7 @@ Requires-Dist: fakeredis[lua]>=2.35.1; extra == "test"
 Requires-Dist: flake8>=6.1.0; extra == "test"
 Requires-Dist: freezegun>=1.4.0; extra == "test"
 Provides-Extra: docs
-Requires-Dist: sphinx>=7.0.0; extra == "docs"
+Requires-Dist: sphinx<9.0.0,>=7.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
 Requires-Dist: sphinx-git>=11.0.0; extra == "docs"
 Requires-Dist: sphinxcontrib-mermaid>=0.7.1; extra == "docs"
@@ -36,7 +36,7 @@ Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
 Requires-Dist: fakeredis[lua]>=2.35.1; extra == "dev"
 Requires-Dist: flake8>=6.1.0; extra == "dev"
 Requires-Dist: freezegun>=1.4.0; extra == "dev"
-Requires-Dist: sphinx>=7.0.0; extra == "dev"
+Requires-Dist: sphinx<9.0.0,>=7.0.0; extra == "dev"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "dev"
 Requires-Dist: sphinx-git>=11.0.0; extra == "dev"
 Requires-Dist: sphinxcontrib-mermaid>=0.7.1; extra == "dev"
@@ -97,7 +97,9 @@ A few intentional behaviors that may surprise newcomers — knowing them up-fron
 
 - **`malloc_key(timeout<=0)` creates a permanent (non-expiring) lock.** Useful for resources whose ownership must outlive process restarts; the caller takes responsibility for releasing via `free_keys`. GC never reclaims it (because expiry is also `-1`). Misuse causes resource leaks — only pass `timeout=0` when you mean "I will manage this lock myself."
 - **`cache_timeout=0` (or negative) creates a permanent soft binding.** Sticks until explicitly overwritten by another `update_soft_bind` for the same name, or removed via `unbind_soft_bind`. Symmetric to the lock-timeout contract above.
-- **`assign()` does not delete the lock keys of items it evicts.** A deliberate write-amplification trade-off: locks expire on their own TTL, and if the same key is later re-`extend`-ed into the pool, the new `extend`/`assign` clears any residual lock so the new entry starts clean. If you evict a key and never re-add it, the lock is an orphan — callers who care must `DEL <prefix>|<suffix>:<key>` themselves.
+- **`malloc()` and `malloc_key()` return `None` when no resource is available.** Check the return value before using it; an empty pool is not represented as a wrapper with `key=None`.
+- **Prefer `with allocator.malloc(...) as allocation:` or `allocation.release()` for object allocations.** `release()` closes the wrapped object and returns the key to the pool. Plain `close()` only closes the wrapped object and leaves allocation ownership unchanged for callers that manage `free()` manually.
+- **`assign()` / `shrink()` / `clear()` are not namespace scrubbers.** `assign()` and `shrink()` remove pool membership but intentionally leave lock keys for removed members; `clear()` deletes the pool hash/head/tail only. This avoids write amplification and wildcard scans, but an evicted permanent lock becomes a permanent orphan. To recover a known orphan, call `free_keys(key)`, reintroduce that same key with `extend([key])` or `assign([... key ...])`, or delete `<prefix>|<suffix>:<key>` directly. Reintroducing unrelated keys, `clear()`, and `gc()` do not remove orphan locks outside the pool.
 - **Pool keys are validated at the API boundary.** `extend()` / `assign()` raise `ValueError` for keys that are empty, equal to the literal `"#ALLOCATED"`, contain the `"||"` separator, contain NUL bytes, or are not strings. These shapes break the on-disk encoding and would silently corrupt the linked list.
 
 ## Documentation
@@ -227,15 +229,13 @@ if key:
 # Allocate a resource with object (returns a RedisAllocatorObject)
 allocated_obj = allocator.malloc(timeout=120)
 if allocated_obj:
-    try:
+    with allocated_obj:
         # The key is available as a property
         print(f"Allocated resource: {allocated_obj.key}")
         
         # Update the resource's lock timeout
         allocated_obj.update(timeout=60)
-    finally:
-        # Free the resource when done
-        allocator.free(allocated_obj)
+    # Leaving the with block calls allocated_obj.release().
 
 # Using soft binding (associates a name with a resource)
 allocator.update_soft_bind("worker-1", "resource-1")
@@ -461,7 +461,7 @@ result = task_queue.query(
     id="task-123",
     name="example-task",
     params={"input": "data"},
-    timeout=300,  # Optional timeout in seconds
+    timeout=300,  # End-to-end wait timeout in seconds for remote execution
     policy=TaskExecutePolicy.Auto,  # Execution policy
     once=False  # Whether to delete the result after getting it
 )
@@ -498,10 +498,40 @@ The RedisAllocator maintains resources in a doubly-linked list structure stored
 
 ### Concurrency Safety
 
-Each EVAL is atomic on Redis (single-threaded server, Lua never preempted), so no operation can be observed half-completed. Multi-process coordination is then provided by lock TTL plus the GC pass — a process killed mid-sequence leaves at most an orphaned lock, which expires on its TTL or is reclaimed by GC.
+Each EVAL is atomic on Redis (single-threaded server, Lua never preempted), so no operation can be observed half-completed. Multi-process coordination is then provided by lock TTL plus the GC pass. A process killed after allocation can leave a lock behind. If the resource is still present in pool metadata, the lock either expires naturally or is reconciled by GC; if the resource is later evicted by `assign()` / `shrink()` / `clear()`, the lock becomes an orphan outside GC scope and expires only by TTL unless it is permanent.
 
 The pool linked-list invariants survive arbitrary interleaving of `malloc` / `free` / `extend` / `assign` / `gc` from concurrent processes (validated by both fakeredis multi-thread tests and a Docker-backed stress driver — see Testing below). If you observe persistent invariant violations under load, please file an issue with the operation sequence.
 
+#### Atomic Operation Boundaries
+
+Allocator state transitions are written as single Redis Lua scripts. Redis runs each script atomically on the server event loop, so concurrent processes cannot observe a half-updated free-list node, lock key, or soft-binding update. This guarantee depends on using one Redis instance; Redis Cluster is out of scope because the allocator mutates multiple related keys in one script.
+
+| Operation | Atomic boundary | Notes |
+|---|---|---|
+| `malloc_key()` | One Lua EVAL | Checks soft binding, pops/rotates the free-list head, marks the item allocated, creates the lock key, and refreshes binding state together. |
+| `free_keys()` | One Lua EVAL | Deletes lock keys and returns still-present pool members to the free-list tail together. Unknown or evicted keys are no-ops. |
+| `extend()` / `shrink()` / `assign()` | One Lua EVAL per call | Batch updates are atomic as a batch. `assign()` and `shrink()` intentionally preserve lock keys for evicted members; `extend()` / `assign()` delete a residual lock only when that same key is newly added to the pool. |
+| `clear()` | One Lua EVAL | Deletes the pool hash plus head/tail pointers only; it does not scan or delete per-resource lock keys. |
+| `gc()` | One Lua EVAL per pass | Incrementally reconciles up to the requested scan count and saves the scan cursor. |
+| `malloc()` / `RedisAllocatorObject.release()` | Wrapper around atomic calls | `malloc()` wraps `malloc_key()` after the atomic allocation; `release()` wraps `free_keys()` after closing the local object. |
+
+Multi-process coordination is provided by those atomic scripts plus lock TTLs and GC. A process killed after allocation may leave a lock behind; pool-member locks either expire naturally or are reconciled by GC. Orphan locks whose key is no longer in the pool are outside GC scope. Permanent locks (`timeout <= 0`) are never reclaimed automatically and must be released explicitly with `free_keys(key)`, by reintroducing that same key with `extend([key])` or `assign([... key ...])`, or by deleting `<prefix>|<suffix>:<key>` directly.
+
+### Operation Complexity
+
+The hot path is designed to avoid scanning the whole pool. Use `malloc_key()` / `free_keys()` for high-frequency allocation, use `extend()` for incremental pool refreshes, and reserve `assign()` for lower-frequency wholesale replacement.
+
+| Operation | Time complexity | Space / Redis writes | Recommended use |
+|---|---:|---|---|
+| `malloc_key()` | Amortized `O(1)`; worst-case `O(k)` when skipping `k` expired or locked head entries | Constant extra metadata writes | Hot path allocation. |
+| `free_keys(n)` | `O(n)` | Constant writes per released key | Hot path release; single-key free is `O(1)`. |
+| `extend(n)` | `O(n)`, independent of existing pool size | Constant writes per supplied key | Incremental pool additions or expiry refresh. |
+| `shrink(n)` | `O(n)` | Constant writes per supplied key | Remove known resources. |
+| `assign(n)` | `O(current_pool_size + n)` | Rewrites membership for removed/new keys | Low-frequency full replacement. |
+| `gc(count)` | Approximately `O(count)` per pass | Bounded by scanned entries | Periodic incremental repair/reclaim. |
+
+`k` in `malloc_key()` is the number of stale head entries cleaned during that allocation. Those entries are removed or marked allocated as they are skipped, so the cost is paid once and amortizes over later calls.
+
 ## Testing
 
 The default unit suite is fast (~7s) and self-contained — `pytest` runs it without any external services:
@@ -518,7 +548,7 @@ Several test categories are **opt-in via pytest markers** (excluded from the def
 ```bash
 pytest -m concurrency             # multi-thread fakeredis race tests (~25s)
 pytest -m fuzz                    # randomised single-thread sequences
-pytest -m benchmark               # constant-time complexity assertions for malloc/free/extend
+pytest -m benchmark               # operation-complexity assertions for allocator commands
 pytest -m "concurrency or fuzz or benchmark"   # all of the above
 ```
 
@@ -530,9 +560,41 @@ python tests/stress_pool_corruption.py        # 60s default; STRESS_DURATION/STR
 docker rm -f allocator-stress
 ```
 
-Performance contracts are validated on both backends. Real Redis 7 confirms hard `O(1)` for `malloc + free` and `extend` per-key cost across pool sizes from 10 to 5000 keys. The fakeredis `pytest -m benchmark` enforces the same threshold; it relies on a temporary monkey-patch in `tests/conftest.py` because of [fakeredis upstream PR #473](https://github.com/cunla/fakeredis-py/pull/473) (merged to master, not yet released). The patch is idempotent and self-removable once fakeredis ships a release containing the fix — see the cleanup checklist embedded in `tests/conftest.py`.
+Performance contracts are validated on both backends. The fakeredis `pytest -m benchmark` suite enforces scaling ratios across pool sizes from 10 to 5000 keys for `malloc_key() + free_keys()`, batched `free_keys(n)`, `extend(n)`, `shrink(n)`, and `gc(count)`. It covers `assign(n)` across 10 to 1000 keys because fakeredis/lupa is unreliable with 5000+ Lua ARGV on Windows; the real Redis script covers `assign(n)` through 5000. The benchmark asserts operation cost follows the documented complexity table instead of silently regressing to full-pool scans. It relies on a temporary monkey-patch in `tests/conftest.py` because of [fakeredis upstream PR #473](https://github.com/cunla/fakeredis-py/pull/473) (merged to master, not yet released). The patch is idempotent and self-removable once fakeredis ships a release containing the fix — see the cleanup checklist embedded in `tests/conftest.py`.
+
+A standalone Python script `tests/_perf_real_redis.py` reproduces the same operation-complexity benchmark against a real Redis container for cross-checking and exits non-zero when a contract fails.
+
+## Live Diagnostics
+
+`redis-allocator` includes an observer-only diagnostics API and local dashboard for inspecting live allocator state under multi-process load.
+
+Python API:
+
+```python
+from redis import Redis
+from redis_allocator import RedisAllocatorDiagnostics
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+diagnostics = RedisAllocatorDiagnostics(redis, prefix="myapp", suffix="allocator")
+snapshot = diagnostics.snapshot()
+print(snapshot.to_json(indent=2))
+```
+
+One-shot JSON:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --json
+```
+
+Live dashboard:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --interval 1 --port 8765
+```
+
+The diagnostics collector reads pool structure and per-pool-key lock state atomically with one Lua script. Advisory metrics such as Redis memory, commandstats, slowlog, soft bindings, and orphan locks are sampled separately. V1 never mutates allocator state and does not repair corruption. Orphan-lock samples are reporting only: clean a known orphan with `free_keys(key)`, by reintroducing the same key through `extend()` / `assign()`, or with a precise Redis `DEL`; `clear()` and `gc()` do not repair orphan locks outside the pool.
 
-A standalone Python script `tests/_perf_real_redis.py` reproduces the benchmark against a real Redis container for cross-checking.
+Use `sample_limit` to bound returned examples and `scan_limit` to cap advisory keyspace scans during dashboard refreshes. When a scan is capped, the JSON marks that section as `truncated`.
 
 ## Roadmap
 

{redis_allocator-0.6.1 → redis_allocator-0.7.0}/README.md

@@ -42,7 +42,9 @@ A few intentional behaviors that may surprise newcomers — knowing them up-fron
 
 - **`malloc_key(timeout<=0)` creates a permanent (non-expiring) lock.** Useful for resources whose ownership must outlive process restarts; the caller takes responsibility for releasing via `free_keys`. GC never reclaims it (because expiry is also `-1`). Misuse causes resource leaks — only pass `timeout=0` when you mean "I will manage this lock myself."
 - **`cache_timeout=0` (or negative) creates a permanent soft binding.** Sticks until explicitly overwritten by another `update_soft_bind` for the same name, or removed via `unbind_soft_bind`. Symmetric to the lock-timeout contract above.
-- **`assign()` does not delete the lock keys of items it evicts.** A deliberate write-amplification trade-off: locks expire on their own TTL, and if the same key is later re-`extend`-ed into the pool, the new `extend`/`assign` clears any residual lock so the new entry starts clean. If you evict a key and never re-add it, the lock is an orphan — callers who care must `DEL <prefix>|<suffix>:<key>` themselves.
+- **`malloc()` and `malloc_key()` return `None` when no resource is available.** Check the return value before using it; an empty pool is not represented as a wrapper with `key=None`.
+- **Prefer `with allocator.malloc(...) as allocation:` or `allocation.release()` for object allocations.** `release()` closes the wrapped object and returns the key to the pool. Plain `close()` only closes the wrapped object and leaves allocation ownership unchanged for callers that manage `free()` manually.
+- **`assign()` / `shrink()` / `clear()` are not namespace scrubbers.** `assign()` and `shrink()` remove pool membership but intentionally leave lock keys for removed members; `clear()` deletes the pool hash/head/tail only. This avoids write amplification and wildcard scans, but an evicted permanent lock becomes a permanent orphan. To recover a known orphan, call `free_keys(key)`, reintroduce that same key with `extend([key])` or `assign([... key ...])`, or delete `<prefix>|<suffix>:<key>` directly. Reintroducing unrelated keys, `clear()`, and `gc()` do not remove orphan locks outside the pool.
 - **Pool keys are validated at the API boundary.** `extend()` / `assign()` raise `ValueError` for keys that are empty, equal to the literal `"#ALLOCATED"`, contain the `"||"` separator, contain NUL bytes, or are not strings. These shapes break the on-disk encoding and would silently corrupt the linked list.
 
 ## Documentation
@@ -172,15 +174,13 @@ if key:
 # Allocate a resource with object (returns a RedisAllocatorObject)
 allocated_obj = allocator.malloc(timeout=120)
 if allocated_obj:
-    try:
+    with allocated_obj:
         # The key is available as a property
         print(f"Allocated resource: {allocated_obj.key}")
         
         # Update the resource's lock timeout
         allocated_obj.update(timeout=60)
-    finally:
-        # Free the resource when done
-        allocator.free(allocated_obj)
+    # Leaving the with block calls allocated_obj.release().
 
 # Using soft binding (associates a name with a resource)
 allocator.update_soft_bind("worker-1", "resource-1")
@@ -406,7 +406,7 @@ result = task_queue.query(
     id="task-123",
     name="example-task",
     params={"input": "data"},
-    timeout=300,  # Optional timeout in seconds
+    timeout=300,  # End-to-end wait timeout in seconds for remote execution
     policy=TaskExecutePolicy.Auto,  # Execution policy
     once=False  # Whether to delete the result after getting it
 )
@@ -443,10 +443,40 @@ The RedisAllocator maintains resources in a doubly-linked list structure stored
 
 ### Concurrency Safety
 
-Each EVAL is atomic on Redis (single-threaded server, Lua never preempted), so no operation can be observed half-completed. Multi-process coordination is then provided by lock TTL plus the GC pass — a process killed mid-sequence leaves at most an orphaned lock, which expires on its TTL or is reclaimed by GC.
+Each EVAL is atomic on Redis (single-threaded server, Lua never preempted), so no operation can be observed half-completed. Multi-process coordination is then provided by lock TTL plus the GC pass. A process killed after allocation can leave a lock behind. If the resource is still present in pool metadata, the lock either expires naturally or is reconciled by GC; if the resource is later evicted by `assign()` / `shrink()` / `clear()`, the lock becomes an orphan outside GC scope and expires only by TTL unless it is permanent.
 
 The pool linked-list invariants survive arbitrary interleaving of `malloc` / `free` / `extend` / `assign` / `gc` from concurrent processes (validated by both fakeredis multi-thread tests and a Docker-backed stress driver — see Testing below). If you observe persistent invariant violations under load, please file an issue with the operation sequence.
 
+#### Atomic Operation Boundaries
+
+Allocator state transitions are written as single Redis Lua scripts. Redis runs each script atomically on the server event loop, so concurrent processes cannot observe a half-updated free-list node, lock key, or soft-binding update. This guarantee depends on using one Redis instance; Redis Cluster is out of scope because the allocator mutates multiple related keys in one script.
+
+| Operation | Atomic boundary | Notes |
+|---|---|---|
+| `malloc_key()` | One Lua EVAL | Checks soft binding, pops/rotates the free-list head, marks the item allocated, creates the lock key, and refreshes binding state together. |
+| `free_keys()` | One Lua EVAL | Deletes lock keys and returns still-present pool members to the free-list tail together. Unknown or evicted keys are no-ops. |
+| `extend()` / `shrink()` / `assign()` | One Lua EVAL per call | Batch updates are atomic as a batch. `assign()` and `shrink()` intentionally preserve lock keys for evicted members; `extend()` / `assign()` delete a residual lock only when that same key is newly added to the pool. |
+| `clear()` | One Lua EVAL | Deletes the pool hash plus head/tail pointers only; it does not scan or delete per-resource lock keys. |
+| `gc()` | One Lua EVAL per pass | Incrementally reconciles up to the requested scan count and saves the scan cursor. |
+| `malloc()` / `RedisAllocatorObject.release()` | Wrapper around atomic calls | `malloc()` wraps `malloc_key()` after the atomic allocation; `release()` wraps `free_keys()` after closing the local object. |
+
+Multi-process coordination is provided by those atomic scripts plus lock TTLs and GC. A process killed after allocation may leave a lock behind; pool-member locks either expire naturally or are reconciled by GC. Orphan locks whose key is no longer in the pool are outside GC scope. Permanent locks (`timeout <= 0`) are never reclaimed automatically and must be released explicitly with `free_keys(key)`, by reintroducing that same key with `extend([key])` or `assign([... key ...])`, or by deleting `<prefix>|<suffix>:<key>` directly.
+
+### Operation Complexity
+
+The hot path is designed to avoid scanning the whole pool. Use `malloc_key()` / `free_keys()` for high-frequency allocation, use `extend()` for incremental pool refreshes, and reserve `assign()` for lower-frequency wholesale replacement.
+
+| Operation | Time complexity | Space / Redis writes | Recommended use |
+|---|---:|---|---|
+| `malloc_key()` | Amortized `O(1)`; worst-case `O(k)` when skipping `k` expired or locked head entries | Constant extra metadata writes | Hot path allocation. |
+| `free_keys(n)` | `O(n)` | Constant writes per released key | Hot path release; single-key free is `O(1)`. |
+| `extend(n)` | `O(n)`, independent of existing pool size | Constant writes per supplied key | Incremental pool additions or expiry refresh. |
+| `shrink(n)` | `O(n)` | Constant writes per supplied key | Remove known resources. |
+| `assign(n)` | `O(current_pool_size + n)` | Rewrites membership for removed/new keys | Low-frequency full replacement. |
+| `gc(count)` | Approximately `O(count)` per pass | Bounded by scanned entries | Periodic incremental repair/reclaim. |
+
+`k` in `malloc_key()` is the number of stale head entries cleaned during that allocation. Those entries are removed or marked allocated as they are skipped, so the cost is paid once and amortizes over later calls.
+
 ## Testing
 
 The default unit suite is fast (~7s) and self-contained — `pytest` runs it without any external services:
@@ -463,7 +493,7 @@ Several test categories are **opt-in via pytest markers** (excluded from the def
 ```bash
 pytest -m concurrency             # multi-thread fakeredis race tests (~25s)
 pytest -m fuzz                    # randomised single-thread sequences
-pytest -m benchmark               # constant-time complexity assertions for malloc/free/extend
+pytest -m benchmark               # operation-complexity assertions for allocator commands
 pytest -m "concurrency or fuzz or benchmark"   # all of the above
 ```
 
@@ -475,9 +505,41 @@ python tests/stress_pool_corruption.py        # 60s default; STRESS_DURATION/STR
 docker rm -f allocator-stress
 ```
 
-Performance contracts are validated on both backends. Real Redis 7 confirms hard `O(1)` for `malloc + free` and `extend` per-key cost across pool sizes from 10 to 5000 keys. The fakeredis `pytest -m benchmark` enforces the same threshold; it relies on a temporary monkey-patch in `tests/conftest.py` because of [fakeredis upstream PR #473](https://github.com/cunla/fakeredis-py/pull/473) (merged to master, not yet released). The patch is idempotent and self-removable once fakeredis ships a release containing the fix — see the cleanup checklist embedded in `tests/conftest.py`.
+Performance contracts are validated on both backends. The fakeredis `pytest -m benchmark` suite enforces scaling ratios across pool sizes from 10 to 5000 keys for `malloc_key() + free_keys()`, batched `free_keys(n)`, `extend(n)`, `shrink(n)`, and `gc(count)`. It covers `assign(n)` across 10 to 1000 keys because fakeredis/lupa is unreliable with 5000+ Lua ARGV on Windows; the real Redis script covers `assign(n)` through 5000. The benchmark asserts operation cost follows the documented complexity table instead of silently regressing to full-pool scans. It relies on a temporary monkey-patch in `tests/conftest.py` because of [fakeredis upstream PR #473](https://github.com/cunla/fakeredis-py/pull/473) (merged to master, not yet released). The patch is idempotent and self-removable once fakeredis ships a release containing the fix — see the cleanup checklist embedded in `tests/conftest.py`.
+
+A standalone Python script `tests/_perf_real_redis.py` reproduces the same operation-complexity benchmark against a real Redis container for cross-checking and exits non-zero when a contract fails.
+
+## Live Diagnostics
+
+`redis-allocator` includes an observer-only diagnostics API and local dashboard for inspecting live allocator state under multi-process load.
+
+Python API:
+
+```python
+from redis import Redis
+from redis_allocator import RedisAllocatorDiagnostics
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+diagnostics = RedisAllocatorDiagnostics(redis, prefix="myapp", suffix="allocator")
+snapshot = diagnostics.snapshot()
+print(snapshot.to_json(indent=2))
+```
+
+One-shot JSON:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --json
+```
+
+Live dashboard:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --interval 1 --port 8765
+```
+
+The diagnostics collector reads pool structure and per-pool-key lock state atomically with one Lua script. Advisory metrics such as Redis memory, commandstats, slowlog, soft bindings, and orphan locks are sampled separately. V1 never mutates allocator state and does not repair corruption. Orphan-lock samples are reporting only: clean a known orphan with `free_keys(key)`, by reintroducing the same key through `extend()` / `assign()`, or with a precise Redis `DEL`; `clear()` and `gc()` do not repair orphan locks outside the pool.
 
-A standalone Python script `tests/_perf_real_redis.py` reproduces the benchmark against a real Redis container for cross-checking.
+Use `sample_limit` to bound returned examples and `scan_limit` to cap advisory keyspace scans during dashboard refreshes. When a scan is capped, the JSON marks that section as `truncated`.
 
 ## Roadmap
 

{redis_allocator-0.6.1 → redis_allocator-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'setuptools.build_meta'
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.6.1"
+version = "0.7.0"
 tag_format = "v$version"
 
 [tool.commitizen.version_files]
@@ -16,7 +16,8 @@ tag_format = "v$version"
 # Run them explicitly with:
 #     pytest -m concurrency           # multi-thread fakeredis race tests
 #     pytest -m fuzz                  # randomised single-thread sequences
-#     pytest -m "concurrency or fuzz"
+#     pytest -m benchmark             # allocator operation-complexity contracts
+#     pytest -m "concurrency or fuzz or benchmark"
 markers = [
     "concurrency: tests that drive the allocator from multiple threads (fakeredis)",
     "fuzz: random-sequence exploratory tests (may exercise lupa edge cases)",

{redis_allocator-0.6.1 → redis_allocator-0.7.0}/redis_allocator/__init__.py

@@ -9,6 +9,7 @@ from redis_allocator.lock import (RedisLock, RedisLockPool, LockStatus,
                                   BaseLock, BaseLockPool, ThreadLock, ThreadLockPool)
 from redis_allocator.task_queue import TaskExecutePolicy, RedisTask, RedisTaskQueue
 from redis_allocator.allocator import RedisAllocator, RedisAllocatorObject, RedisAllocatorUpdater, RedisAllocatorPolicy, DefaultRedisAllocatorPolicy
+from redis_allocator.diagnostics import RedisAllocatorDiagnostics
 
 
 __version__ = '0.0.1'
@@ -29,4 +30,5 @@ __all__ = [
     'RedisAllocatorUpdater',
     'RedisAllocatorPolicy',
     'DefaultRedisAllocatorPolicy',
+    'RedisAllocatorDiagnostics',
 ]

redis_allocator-0.7.0/redis_allocator/_version.py

@@ -0,0 +1 @@
+__version__ = '0.7.0'

{redis_allocator-0.6.1 → redis_allocator-0.7.0}/redis_allocator/allocator.py

@@ -153,6 +153,7 @@ class RedisAllocatorObject(Generic[U]):
         self.key = key
         self.obj = obj
         self.params = params
+        self._released = False
         if self.obj is not None:
             self.obj.set_config(key, params)
 
@@ -178,6 +179,32 @@ class RedisAllocatorObject(Generic[U]):
         if self.obj is not None:
             self.obj.close()
 
+    def release(self, timeout: int = -1):
+        """Close the wrapped object and return the allocation to the pool.
+
+        This method is idempotent so callers can safely place it in cleanup
+        paths that may run more than once.
+
+        Args:
+            timeout: Optional timeout in seconds for the returned pool item.
+        """
+        if self._released:
+            return
+        try:
+            self.close()
+        finally:
+            self.allocator.free(self, timeout=timeout)
+            self._released = True
+
+    def __enter__(self):
+        """Open and return this allocated object for ``with`` statements."""
+        return self.open()
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Release this allocation when leaving a ``with`` statement."""
+        self.release()
+        return False
+
     def is_healthy(self) -> bool:
         """Check if the object is healthy."""
         if self.obj is not None:
@@ -456,6 +483,8 @@ class DefaultRedisAllocatorPolicy(RedisAllocatorPolicy[U]):
             obj.name) else (obj.name if obj and hasattr(obj, 'name') else None)
         key = allocator.malloc_key(timeout, obj_name,
                                    cache_timeout=cache_timeout)
+        if key is None:
+            return None
         alloc_obj = RedisAllocatorObject(allocator, key, obj, params)
         if self.auto_close:
             old_obj = self.objects.get(alloc_obj.unique_id, None)
@@ -1271,6 +1300,8 @@ class RedisAllocator(RedisLockPool, Generic[U]):
         # 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)
+        if key is None:
+            return None
         return RedisAllocatorObject(
             self, key, obj, params
         )

redis_allocator-0.7.0/redis_allocator/diagnostics/__init__.py

@@ -0,0 +1,30 @@
+"""Diagnostics helpers for live RedisAllocator instances."""
+
+from redis_allocator.diagnostics.collector import RedisAllocatorDiagnostics
+from redis_allocator.diagnostics.dashboard import create_dashboard_server, serve_dashboard
+from redis_allocator.diagnostics.models import (
+    AllocatorDiagnosticsSnapshot,
+    BindingDiagnostics,
+    IdentityDiagnostics,
+    IntegrityDiagnostics,
+    OrphanDiagnostics,
+    PoolDiagnostics,
+    PressureDiagnostics,
+    Recommendation,
+    RedisDiagnostics,
+)
+
+__all__ = [
+    "AllocatorDiagnosticsSnapshot",
+    "BindingDiagnostics",
+    "IdentityDiagnostics",
+    "IntegrityDiagnostics",
+    "OrphanDiagnostics",
+    "PoolDiagnostics",
+    "PressureDiagnostics",
+    "Recommendation",
+    "RedisAllocatorDiagnostics",
+    "RedisDiagnostics",
+    "create_dashboard_server",
+    "serve_dashboard",
+]

redis_allocator-0.7.0/redis_allocator/diagnostics/cli.py

@@ -0,0 +1,52 @@
+"""Command-line entry point for allocator diagnostics."""
+
+from __future__ import annotations
+
+import argparse
+
+from redis import Redis
+
+from redis_allocator.diagnostics.collector import RedisAllocatorDiagnostics
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the diagnostics CLI parser."""
+    parser = argparse.ArgumentParser(description="Inspect a live RedisAllocator instance.")
+    parser.add_argument("--redis-url", default="redis://localhost:6379/0")
+    parser.add_argument("--prefix", required=True)
+    parser.add_argument("--suffix", default="allocator")
+    parser.add_argument("--shared", action="store_true")
+    parser.add_argument("--sample-limit", type=int, default=20)
+    parser.add_argument("--scan-limit", type=int, default=1000)
+    parser.add_argument("--json", action="store_true", help="Print one JSON snapshot and exit.")
+    parser.add_argument("--interval", type=float, default=1.0)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the diagnostics CLI."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    redis_client = Redis.from_url(args.redis_url, decode_responses=True)
+    diagnostics = RedisAllocatorDiagnostics(
+        redis_client,
+        prefix=args.prefix,
+        suffix=args.suffix,
+        shared=args.shared,
+        sample_limit=args.sample_limit,
+        scan_limit=args.scan_limit,
+    )
+    if args.json:
+        print(diagnostics.snapshot_json(indent=2))
+        return 0
+
+    from redis_allocator.diagnostics.dashboard import serve_dashboard
+
+    serve_dashboard(diagnostics, host=args.host, port=args.port, interval=args.interval)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())