rust-py-cache 0.1.2__tar.gz → 0.2.0__tar.gz

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/Cargo.lock

@@ -202,7 +202,7 @@ dependencies = [
 
 [[package]]
 name = "rust_py_cache"
-version = "0.1.2"
+version = "0.2.0"
 dependencies = [
  "dashmap",
  "pyo3",

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rust_py_cache"
-version = "0.1.2"
+version = "0.2.0"
 edition = "2021"
 readme = "README.md"
 

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rust-py-cache
-Version: 0.1.2
+Version: 0.2.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
@@ -63,7 +63,28 @@ cache.len()                   # approximate size
 cache.keys()                  # list of keys
 cache.cleanup_expired()       # remove expired entries; returns the count
 cache.clear()                 # remove everything (keeps counters)
-cache.stats()                 # {'hits', 'misses', 'sets', 'deletes', 'expired', 'size'}
+cache.stats()                 # {'hits','misses','sets','deletes','expired','evicted','size'}
+```
+
+### Bounded cache with LRU eviction
+
+```python
+# Cap the number of keys. When full and a new key arrives, evict the
+# least-recently-used entry instead of rejecting the write.
+cache = Cache(max_size=1000, eviction_policy="lru")
+cache.eviction_policy            # "lru"
+
+# Default policy is "reject": set() returns False when full (and the key is new).
+cache = Cache(max_size=1000)     # eviction_policy="reject"
+cache.set("a", 1)                # True / False
+```
+
+### Background expiration
+
+```python
+# A background thread reclaims expired entries every N seconds, so you don't
+# have to call cleanup_expired() yourself. It stops when the cache is collected.
+cache = Cache(cleanup_interval=30)   # seconds (int/float)
 ```
 
 ### Memoization decorator
@@ -86,9 +107,13 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
 
 ## API
 
+Constructor: `Cache(max_size=None, eviction_policy="reject", cleanup_interval=None)`.
+`eviction_policy` must be `"reject"` or `"lru"` (any other value raises
+`ValueError`). `cleanup_interval` (seconds, `> 0`) enables the background sweeper.
+
 | Method | Description |
 |---|---|
-| `set(key, value, ttl=None)` | Store a value. `ttl` in seconds (`int`/`float`); `None` = no expiration; `ttl <= 0` → `ValueError`. Overwrites. |
+| `set(key, value, ttl=None)` | Store a value. `ttl` in seconds (`int`/`float`); `None` = no expiration; `ttl <= 0` → `ValueError`. Overwrites. Returns `True`, or `False` when full under `eviction_policy="reject"` and the key is new. |
 | `get(key, default=None)` | The value, or `default` if missing/expired (expired entries are removed). |
 | `delete(key)` | `True` if removed, `False` if it didn't exist. |
 | `exists(key)` | `True`/`False`, honoring TTL. |
@@ -96,7 +121,8 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
 | `len()` / `len(cache)` | Approximate size. |
 | `clear()` | Remove everything (does not reset counters). |
 | `cleanup_expired()` | Remove expired entries; returns how many. |
-| `stats()` | `dict` with `hits, misses, sets, deletes, expired, size`. |
+| `eviction_policy` (property) | The active policy: `"reject"` or `"lru"`. |
+| `stats()` | `dict` with `hits, misses, sets, deletes, expired, evicted, size`. |
 | `@cache.cached(ttl=None, key=None)` | Memoization decorator. |
 
 ## How it works
@@ -105,8 +131,11 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
   side, via PyO3) and stored as opaque bytes (`Vec<u8>`) in the Rust core.
 - **Concurrency:** `DashMap` (a HashMap with per-shard locks) plus `AtomicU64`
   counters, with no global lock on the hot path. Thread-safe, no busy loop.
-- **TTL:** expiration is **lazy** — an expired key is removed when accessed
-  (`get`/`exists`) or via `cleanup_expired()`. There is no background thread in the MVP.
+- **TTL:** expiration is **lazy** by default — an expired key is removed when
+  accessed (`get`/`exists`) or via `cleanup_expired()`. Pass `cleanup_interval` to
+  also run a **background** sweeper thread that reclaims expired keys on its own.
+- **Eviction:** with `max_size` + `eviction_policy="lru"`, a full cache evicts the
+  least-recently-used entry (recency updated on every `get` hit) to admit a new key.
 
 ## Limitations
 
@@ -114,7 +143,8 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
 - It does **not** replace Redis for distributed caching.
 - Data is **lost** when the process restarts.
 - `pickle` must **not** be used to deserialize untrusted data.
-- Lazy TTL: expired items may linger until accessed or until `cleanup_expired()`.
+- Lazy TTL by default: without `cleanup_interval`, expired items may linger until
+  accessed or until `cleanup_expired()` runs.
 
 ## Development
 

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/README.md

@@ -45,7 +45,28 @@ cache.len()                   # approximate size
 cache.keys()                  # list of keys
 cache.cleanup_expired()       # remove expired entries; returns the count
 cache.clear()                 # remove everything (keeps counters)
-cache.stats()                 # {'hits', 'misses', 'sets', 'deletes', 'expired', 'size'}
+cache.stats()                 # {'hits','misses','sets','deletes','expired','evicted','size'}
+```
+
+### Bounded cache with LRU eviction
+
+```python
+# Cap the number of keys. When full and a new key arrives, evict the
+# least-recently-used entry instead of rejecting the write.
+cache = Cache(max_size=1000, eviction_policy="lru")
+cache.eviction_policy            # "lru"
+
+# Default policy is "reject": set() returns False when full (and the key is new).
+cache = Cache(max_size=1000)     # eviction_policy="reject"
+cache.set("a", 1)                # True / False
+```
+
+### Background expiration
+
+```python
+# A background thread reclaims expired entries every N seconds, so you don't
+# have to call cleanup_expired() yourself. It stops when the cache is collected.
+cache = Cache(cleanup_interval=30)   # seconds (int/float)
 ```
 
 ### Memoization decorator
@@ -68,9 +89,13 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
 
 ## API
 
+Constructor: `Cache(max_size=None, eviction_policy="reject", cleanup_interval=None)`.
+`eviction_policy` must be `"reject"` or `"lru"` (any other value raises
+`ValueError`). `cleanup_interval` (seconds, `> 0`) enables the background sweeper.
+
 | Method | Description |
 |---|---|
-| `set(key, value, ttl=None)` | Store a value. `ttl` in seconds (`int`/`float`); `None` = no expiration; `ttl <= 0` → `ValueError`. Overwrites. |
+| `set(key, value, ttl=None)` | Store a value. `ttl` in seconds (`int`/`float`); `None` = no expiration; `ttl <= 0` → `ValueError`. Overwrites. Returns `True`, or `False` when full under `eviction_policy="reject"` and the key is new. |
 | `get(key, default=None)` | The value, or `default` if missing/expired (expired entries are removed). |
 | `delete(key)` | `True` if removed, `False` if it didn't exist. |
 | `exists(key)` | `True`/`False`, honoring TTL. |
@@ -78,7 +103,8 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
 | `len()` / `len(cache)` | Approximate size. |
 | `clear()` | Remove everything (does not reset counters). |
 | `cleanup_expired()` | Remove expired entries; returns how many. |
-| `stats()` | `dict` with `hits, misses, sets, deletes, expired, size`. |
+| `eviction_policy` (property) | The active policy: `"reject"` or `"lru"`. |
+| `stats()` | `dict` with `hits, misses, sets, deletes, expired, evicted, size`. |
 | `@cache.cached(ttl=None, key=None)` | Memoization decorator. |
 
 ## How it works
@@ -87,8 +113,11 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
   side, via PyO3) and stored as opaque bytes (`Vec<u8>`) in the Rust core.
 - **Concurrency:** `DashMap` (a HashMap with per-shard locks) plus `AtomicU64`
   counters, with no global lock on the hot path. Thread-safe, no busy loop.
-- **TTL:** expiration is **lazy** — an expired key is removed when accessed
-  (`get`/`exists`) or via `cleanup_expired()`. There is no background thread in the MVP.
+- **TTL:** expiration is **lazy** by default — an expired key is removed when
+  accessed (`get`/`exists`) or via `cleanup_expired()`. Pass `cleanup_interval` to
+  also run a **background** sweeper thread that reclaims expired keys on its own.
+- **Eviction:** with `max_size` + `eviction_policy="lru"`, a full cache evicts the
+  least-recently-used entry (recency updated on every `get` hit) to admit a new key.
 
 ## Limitations
 
@@ -96,7 +125,8 @@ See full examples under [`examples/`](./examples) (FastAPI and Django).
 - It does **not** replace Redis for distributed caching.
 - Data is **lost** when the process restarts.
 - `pickle` must **not** be used to deserialize untrusted data.
-- Lazy TTL: expired items may linger until accessed or until `cleanup_expired()`.
+- Lazy TTL by default: without `cleanup_interval`, expired items may linger until
+  accessed or until `cleanup_expired()` runs.
 
 ## Development
 

rust_py_cache-0.2.0/ROADMAP.md

@@ -0,0 +1,92 @@
+# Roadmap — rust-py-cache
+
+Direction for `rust-py-cache`: an ultra-fast, process-local cache for Python with
+a Rust core (PyO3 + maturin). The MVP is intentionally small; this document tracks
+the stages already shipped and what comes next.
+
+> Status legend: ✅ shipped · 🔜 planned (next) · 💡 idea (no version yet) · ⚠️ note
+
+---
+
+## Shipped — current: 0.2.0
+
+- ✅ `Cache` with `set` / `get(default=...)` / `delete` / `exists` / `keys` /
+  `len` / `clear` / `cleanup_expired` / `stats`.
+- ✅ TTL per entry with **lazy expiration** (expired keys are dropped on access or
+  via `cleanup_expired()`).
+- ✅ Cumulative `stats()` (`hits, misses, sets, deletes, expired, size`) backed by
+  `AtomicU64` — no global lock on the hot path.
+- ✅ Memoization decorator `@cache.cached(ttl=..., key=...)` (fixed string or
+  callable key).
+- ✅ Rust core on `DashMap` (per-shard locks); values serialized with `pickle` and
+  stored as opaque bytes (`Vec<u8>`).
+- ✅ Examples for FastAPI and Django.
+
+---
+
+## Shipped — v0.2.0
+
+### Background expiration
+
+- ✅ Opt-in background sweeper thread via `Cache(cleanup_interval=...)` (seconds),
+  reclaiming expired entries proactively instead of relying only on lazy
+  expiration / manual `cleanup_expired()`. The thread is tied to the cache's
+  lifetime (stops on `Drop`) and sleeps in short slices for responsive shutdown.
+
+### LRU eviction
+
+- ✅ `Cache(max_size=..., eviction_policy="lru")` evicts the **least-recently-used**
+  entry once the cap is hit (recency updated on every `get` hit). Default policy
+  is `"reject"` (backward compatible). Evictions are surfaced in `stats()` as an
+  `evicted` counter.
+
+## Planned
+
+### v0.3 — LFU eviction
+
+- 🔜 **Least-frequently-used** eviction policy as an alternative to LRU, selectable
+  at construction time (e.g. `Cache(max_size=..., policy="lfu")`).
+
+### v0.5 — Configurable serializer
+
+- 🔜 Pluggable serialization instead of hard-coded `pickle`: e.g.
+  `Cache(serializer="json" | "pickle" | "msgpack")` or a custom
+  encode/decode pair.
+- ⚠️ Security: `pickle` must not deserialize untrusted data — a JSON/MessagePack
+  option makes the cache safe to share across trust boundaries.
+
+### v0.6 — Namespaces
+
+- 🔜 Logical key namespaces (e.g. `cache.namespace("users")`) so independent
+  features can share one `Cache` instance without key collisions, with per-namespace
+  `clear()` and stats.
+
+---
+
+## Ideas / future (no version assigned)
+
+- 💡 Prometheus metrics exporter (align with `rust-py-monitor`).
+- 💡 Redis synchronization / a distributed tier (today the cache is process-local).
+- 💡 ImmutableLog integration for eviction events
+  (`{"event_type": "cache_evicted", "key": ..., "reason": ...}`).
+- 💡 Binary value formats end-to-end (MessagePack / CBOR / Bincode) for smaller,
+  faster payloads.
+- 💡 Benchmarks suite (throughput vs. `dict`, `cachetools`, in-process Redis).
+
+---
+
+## Known limitations (by design, for now)
+
+- Process-local: multiple workers = multiple independent caches.
+- Not a replacement for Redis in distributed setups.
+- Data is lost on process restart.
+- Lazy TTL: expired items may linger until accessed or `cleanup_expired()` runs
+  (addressed by v0.2).
+
+---
+
+## Contributing to the roadmap
+
+Versions and ordering are indicative and may shift. Bump the version in **both**
+`Cargo.toml` and `pyproject.toml` (kept in sync) plus `__version__`, ship tests
+(`cargo test` + `pytest`), then tag `vX.Y.Z` to trigger the release workflow.

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "rust-py-cache"
-version = "0.1.2"
+version = "0.2.0"
 description = "An ultra-fast local cache for Python, powered by Rust."
 readme = "README.md"
 requires-python = ">=3.10"

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/python/rust_py_cache/__init__.py

@@ -19,4 +19,4 @@ class Cache(_RustCache):
 
 
 __all__ = ["Cache", "hello"]
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/src/cache.rs

@@ -9,6 +9,16 @@ use dashmap::DashMap;
 use crate::entry::CacheEntry;
 use crate::stats::{CacheStats, StatsSnapshot};
 
+/// O que fazer quando `max_size` é atingido e chega uma chave **nova**.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum EvictionPolicy {
+    /// Rejeita a escrita (`set` devolve `false`). Comportamento padrão.
+    #[default]
+    Reject,
+    /// Remove a entrada menos recentemente usada (LRU) para abrir espaço.
+    Lru,
+}
+
 /// Núcleo concorrente do cache.
 ///
 /// `DashMap` é um `HashMap` thread-safe com *sharding*: ele divide o mapa em
@@ -19,18 +29,45 @@ use crate::stats::{CacheStats, StatsSnapshot};
 /// faz *interior mutability* — ele cuida da sincronização internamente, então
 /// não precisamos de `&mut self` nem de um `Mutex` por fora. As `stats` seguem
 /// a mesma ideia com `AtomicU64`.
-#[derive(Debug, Default)]
+#[derive(Debug)]
 pub struct RustCache {
     store: DashMap<String, CacheEntry>,
     stats: CacheStats,
+    /// Limite opcional de número de chaves.
+    max_size: Option<usize>,
+    /// Política aplicada quando o cache enche e chega uma chave nova.
+    eviction_policy: EvictionPolicy,
 }
 
 impl RustCache {
-    /// Cria um cache vazio.
-    pub fn new() -> Self {
+    /// Cria um cache vazio. `max_size = None` => sem limite de chaves.
+    pub fn new(max_size: Option<usize>, eviction_policy: EvictionPolicy) -> Self {
         Self {
             store: DashMap::new(),
             stats: CacheStats::new(),
+            max_size,
+            eviction_policy,
+        }
+    }
+
+    /// A política de evicção configurada.
+    pub fn eviction_policy(&self) -> EvictionPolicy {
+        self.eviction_policy
+    }
+
+    /// Remove a entrada com o menor `last_accessed_at` (a "menos recentemente
+    /// usada"). Varre o mapa uma vez — O(n) só na evicção (caminho raro: cache
+    /// cheio + chave nova). Conta em `evicted`.
+    fn evict_lru(&self) {
+        let oldest = self
+            .store
+            .iter()
+            .min_by_key(|e| e.value().last_accessed_at)
+            .map(|e| e.key().clone());
+        if let Some(key) = oldest {
+            if self.store.remove(&key).is_some() {
+                self.stats.record_evicted();
+            }
         }
     }
 
@@ -39,10 +76,25 @@ impl RustCache {
     /// O core não sabe o que há nos bytes — quem serializa (pickle) é a camada
     /// `lib.rs`, do lado do Python. Aqui só montamos a `CacheEntry` e inserimos.
     /// `insert` no `DashMap` pega o lock só do shard daquela chave.
-    pub fn set(&self, key: String, value: Vec<u8>, expires_at: Option<u64>, now: u64) {
+    ///
+    /// Sobrescrever uma chave existente sempre é permitido. Para uma chave
+    /// **nova** com o cache cheio (`max_size`): com `Reject` devolve `false` sem
+    /// inserir; com `Lru` remove a entrada menos recentemente usada e prossegue.
+    /// Devolve `true` quando a entrada foi (ou seria) gravada.
+    pub fn set(&self, key: String, value: Vec<u8>, expires_at: Option<u64>, now: u64) -> bool {
+        if let Some(max) = self.max_size {
+            if self.store.len() >= max && !self.store.contains_key(&key) {
+                match self.eviction_policy {
+                    EvictionPolicy::Reject => return false,
+                    EvictionPolicy::Lru => self.evict_lru(),
+                }
+            }
+        }
+
         self.store
             .insert(key, CacheEntry::new(value, expires_at, now));
         self.stats.record_set();
+        true
     }
 
     /// Lê os bytes de `key`, aplicando **expiração lazy**.
@@ -57,7 +109,9 @@ impl RustCache {
     /// vivo, travaríamos o mesmo shard contra nós mesmos (deadlock). Por isso
     /// `drop(entry)` **antes** do `remove`.
     pub fn get(&self, key: &str, now: u64) -> Option<Vec<u8>> {
-        let Some(entry) = self.store.get(key) else {
+        // `get_mut` segura o lock de ESCRITA do shard: além de ler o valor,
+        // atualizamos `last_accessed_at`/`hits` (base do LRU) no mesmo acesso.
+        let Some(mut entry) = self.store.get_mut(key) else {
             self.stats.record_miss();
             return None;
         };
@@ -68,8 +122,11 @@ impl RustCache {
             self.stats.record_miss();
             return None;
         }
+        entry.last_accessed_at = now;
+        entry.hits += 1;
+        let value = entry.value.clone();
         self.stats.record_hit();
-        Some(entry.value.clone())
+        Some(value)
     }
 
     /// `true` se `key` existe e **não** está expirada. Coleta a chave se expirada.
@@ -166,7 +223,7 @@ mod tests {
 
     #[test]
     fn set_then_get_returns_value() {
-        let c = RustCache::new();
+        let c = RustCache::new(None, EvictionPolicy::Reject);
         c.set("a".into(), b"v".to_vec(), None, NOW);
         assert_eq!(c.get("a", NOW), Some(b"v".to_vec()));
         assert_eq!(c.len(), 1);
@@ -174,14 +231,14 @@ mod tests {
 
     #[test]
     fn get_missing_is_none_and_counts_miss() {
-        let c = RustCache::new();
+        let c = RustCache::new(None, EvictionPolicy::Reject);
         assert_eq!(c.get("x", NOW), None);
         assert_eq!(c.stats().misses, 1);
     }
 
     #[test]
     fn expired_get_collects_and_counts() {
-        let c = RustCache::new();
+        let c = RustCache::new(None, EvictionPolicy::Reject);
         c.set("a".into(), b"v".to_vec(), Some(NOW + 10), NOW);
         // ainda válido
         assert!(c.get("a", NOW + 5).is_some());
@@ -196,7 +253,7 @@ mod tests {
 
     #[test]
     fn exists_respects_ttl() {
-        let c = RustCache::new();
+        let c = RustCache::new(None, EvictionPolicy::Reject);
         c.set("a".into(), b"v".to_vec(), Some(NOW + 10), NOW);
         assert!(c.exists("a", NOW + 5));
         assert!(!c.exists("a", NOW + 20));
@@ -205,7 +262,7 @@ mod tests {
 
     #[test]
     fn delete_counts_only_real_removals() {
-        let c = RustCache::new();
+        let c = RustCache::new(None, EvictionPolicy::Reject);
         c.set("a".into(), b"v".to_vec(), None, NOW);
         assert!(c.delete("a"));
         assert!(!c.delete("a"));
@@ -214,7 +271,7 @@ mod tests {
 
     #[test]
     fn cleanup_removes_only_expired() {
-        let c = RustCache::new();
+        let c = RustCache::new(None, EvictionPolicy::Reject);
         c.set("keep".into(), b"v".to_vec(), None, NOW);
         c.set("gone".into(), b"v".to_vec(), Some(NOW + 10), NOW);
         let removed = c.cleanup_expired(NOW + 20);
@@ -223,4 +280,43 @@ mod tests {
         assert!(!c.exists("gone", NOW + 20));
         assert_eq!(c.stats().expired, 1);
     }
+
+    #[test]
+    fn reject_policy_blocks_new_keys_when_full() {
+        let c = RustCache::new(Some(2), EvictionPolicy::Reject);
+        assert!(c.set("a".into(), b"1".to_vec(), None, NOW));
+        assert!(c.set("b".into(), b"2".to_vec(), None, NOW));
+        // cheio + chave nova => rejeita, sem evicção
+        assert!(!c.set("c".into(), b"3".to_vec(), None, NOW));
+        assert_eq!(c.len(), 2);
+        assert_eq!(c.stats().evicted, 0);
+        // sobrescrever chave existente é sempre permitido
+        assert!(c.set("a".into(), b"10".to_vec(), None, NOW));
+    }
+
+    #[test]
+    fn lru_policy_evicts_least_recently_used() {
+        let c = RustCache::new(Some(2), EvictionPolicy::Lru);
+        c.set("a".into(), b"1".to_vec(), None, NOW);
+        c.set("b".into(), b"2".to_vec(), None, NOW);
+        // Acessa "a" mais tarde: "b" vira a menos recentemente usada.
+        assert!(c.get("a", NOW + 5).is_some());
+        // Insere "c": remove "b" (LRU), mantém "a" e "c".
+        assert!(c.set("c".into(), b"3".to_vec(), None, NOW + 10));
+        assert_eq!(c.len(), 2);
+        assert_eq!(c.stats().evicted, 1);
+        assert!(c.get("b", NOW + 11).is_none());
+        assert!(c.get("a", NOW + 11).is_some());
+        assert!(c.get("c", NOW + 11).is_some());
+    }
+
+    #[test]
+    fn no_max_size_never_evicts() {
+        let c = RustCache::new(None, EvictionPolicy::Lru);
+        for i in 0..50 {
+            c.set(format!("k{i}"), b"v".to_vec(), None, NOW);
+        }
+        assert_eq!(c.len(), 50);
+        assert_eq!(c.stats().evicted, 0);
+    }
 }

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/src/lib.rs

@@ -6,13 +6,18 @@
 mod cache;
 mod entry;
 mod stats;
+mod sweeper;
 mod ttl;
 
+use std::sync::Arc;
+use std::time::Duration;
+
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
 use pyo3::types::{PyBytes, PyDict};
 
-use crate::cache::RustCache;
+use crate::cache::{EvictionPolicy, RustCache};
+use crate::sweeper::Sweeper;
 use crate::ttl::{expires_at_from_ttl, now_ms};
 
 /// Serializa um objeto Python em bytes via `pickle.dumps`.
@@ -57,19 +62,61 @@ fn hello() -> PyResult<String> {
 ///   adiciona o decorator `@cache.cached` (ver `python/.../decorators.py`).
 #[pyclass(subclass)]
 pub struct Cache {
-    inner: RustCache,
+    inner: Arc<RustCache>,
+    /// Thread de expiração em background (quando `cleanup_interval` é dado).
+    /// Mantida viva junto com o `Cache`; encerrada no `Drop`. O `_` evita o aviso
+    /// de campo não lido — seu efeito é o ciclo de vida, não a leitura.
+    _sweeper: Option<Sweeper>,
 }
 
 #[pymethods]
 impl Cache {
-    /// `Cache()` — cria um cache vazio.
+    /// `Cache(max_size=None, eviction_policy="reject", cleanup_interval=None)`.
     ///
-    /// `#[new]` marca o construtor. Devolver `Self` basta: o PyO3 embrulha o
-    /// valor Rust no objeto Python.
+    /// - `max_size`: limite de chaves (`None` = ilimitado).
+    /// - `eviction_policy`: `"reject"` (padrão) ou `"lru"` (remove a menos
+    ///   recentemente usada ao encher). Outro valor levanta `ValueError`.
+    /// - `cleanup_interval`: se `> 0`, liga uma thread que varre expirados a cada
+    ///   N segundos (expiração em background, além da preguiçosa por acesso).
     #[new]
-    fn new() -> Self {
-        Cache {
-            inner: RustCache::new(),
+    #[pyo3(signature = (max_size=None, eviction_policy="reject", cleanup_interval=None))]
+    fn new(
+        max_size: Option<usize>,
+        eviction_policy: &str,
+        cleanup_interval: Option<f64>,
+    ) -> PyResult<Self> {
+        let policy = match eviction_policy {
+            "reject" => EvictionPolicy::Reject,
+            "lru" => EvictionPolicy::Lru,
+            other => {
+                return Err(PyValueError::new_err(format!(
+                    "eviction_policy deve ser \"reject\" ou \"lru\", recebido {other:?}"
+                )));
+            }
+        };
+
+        let inner = Arc::new(RustCache::new(max_size, policy));
+
+        let sweeper = match cleanup_interval {
+            Some(secs) if secs > 0.0 => Some(Sweeper::start(
+                &inner,
+                Duration::from_millis((secs * 1000.0) as u64),
+            )),
+            _ => None,
+        };
+
+        Ok(Cache {
+            inner,
+            _sweeper: sweeper,
+        })
+    }
+
+    /// A política de evicção ativa: `"reject"` ou `"lru"`.
+    #[getter]
+    fn eviction_policy(&self) -> &'static str {
+        match self.inner.eviction_policy() {
+            EvictionPolicy::Reject => "reject",
+            EvictionPolicy::Lru => "lru",
         }
     }
 
@@ -84,6 +131,9 @@ impl Cache {
     ///   seguramos o GIL — necessário para chamar `pickle`.
     /// - `value: &Bound<'_, PyAny>` é qualquer objeto Python, emprestado.
     /// - `#[pyo3(signature = ...)]` define o default `ttl=None` visível no Python.
+    /// Devolve `True` quando a entrada foi gravada; `False` apenas quando há
+    /// `max_size` com `eviction_policy="reject"`, a chave é nova e o cache está
+    /// cheio. Sobrescrever uma chave existente sempre devolve `True`.
     #[pyo3(signature = (key, value, ttl=None))]
     fn set(
         &self,
@@ -91,13 +141,12 @@ impl Cache {
         key: String,
         value: &Bound<'_, PyAny>,
         ttl: Option<f64>,
-    ) -> PyResult<()> {
+    ) -> PyResult<bool> {
         let now = now_ms();
         let expires_at = expires_at_from_ttl(ttl, now)
             .map_err(|_| PyValueError::new_err("ttl deve ser > 0 (ou None para não expirar)"))?;
         let bytes = dumps(py, value)?;
-        self.inner.set(key, bytes, expires_at, now);
-        Ok(())
+        Ok(self.inner.set(key, bytes, expires_at, now))
     }
 
     /// `get(key, default=None)` — devolve o valor de `key`.
@@ -147,6 +196,7 @@ impl Cache {
         d.set_item("sets", s.sets)?;
         d.set_item("deletes", s.deletes)?;
         d.set_item("expired", s.expired)?;
+        d.set_item("evicted", s.evicted)?;
         d.set_item("size", self.inner.len())?;
         Ok(d)
     }

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/src/stats.rs

@@ -18,6 +18,7 @@ pub struct CacheStats {
     pub sets: AtomicU64,
     pub deletes: AtomicU64,
     pub expired: AtomicU64,
+    pub evicted: AtomicU64,
 }
 
 /// Cópia "congelada" dos contadores num instante — fácil de mandar pro Python.
@@ -28,6 +29,7 @@ pub struct StatsSnapshot {
     pub sets: u64,
     pub deletes: u64,
     pub expired: u64,
+    pub evicted: u64,
 }
 
 impl CacheStats {
@@ -57,6 +59,11 @@ impl CacheStats {
         self.expired.fetch_add(n, Ordering::Relaxed);
     }
 
+    /// Conta uma entrada removida por evicção (política LRU ao atingir `max_size`).
+    pub fn record_evicted(&self) {
+        self.evicted.fetch_add(1, Ordering::Relaxed);
+    }
+
     pub fn snapshot(&self) -> StatsSnapshot {
         StatsSnapshot {
             hits: self.hits.load(Ordering::Relaxed),
@@ -64,6 +71,7 @@ impl CacheStats {
             sets: self.sets.load(Ordering::Relaxed),
             deletes: self.deletes.load(Ordering::Relaxed),
             expired: self.expired.load(Ordering::Relaxed),
+            evicted: self.evicted.load(Ordering::Relaxed),
         }
     }
 }

rust_py_cache-0.2.0/src/sweeper.rs

@@ -0,0 +1,77 @@
+//! Expiração em background: uma thread que varre as entradas expiradas em
+//! intervalos regulares, em vez de depender só da expiração preguiçosa (lazy)
+//! ou de chamadas manuais a `cleanup_expired()`.
+//!
+//! ## Ciclo de vida
+//!
+//! A thread recebe um [`Weak<RustCache>`], não um `Arc` forte: assim ela **não**
+//! mantém o cache vivo. Se o objeto `Cache` do Python for coletado, o `Arc` some,
+//! o `upgrade()` falha e a thread encerra sozinha. Além disso o `Cache` guarda
+//! este [`Sweeper`]; quando ele é destruído (`Drop`), sinalizamos a parada e
+//! fazemos `join` — sem threads órfãs.
+//!
+//! O sono é em fatias curtas (não um único `sleep(interval)`) para o encerramento
+//! responder rápido ao sinal de parada, sem esperar o intervalo inteiro.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Weak};
+use std::thread::{self, JoinHandle};
+use std::time::Duration;
+
+use crate::cache::RustCache;
+use crate::ttl::now_ms;
+
+/// Handle da thread de varredura. Pára e faz `join` automaticamente no `Drop`.
+pub struct Sweeper {
+    stop: Arc<AtomicBool>,
+    handle: Option<JoinHandle<()>>,
+}
+
+impl Sweeper {
+    /// Inicia a thread que varre `cache` a cada `interval`.
+    pub fn start(cache: &Arc<RustCache>, interval: Duration) -> Self {
+        let stop = Arc::new(AtomicBool::new(false));
+        let stop_thread = Arc::clone(&stop);
+        let weak = Arc::downgrade(cache);
+        let handle = thread::spawn(move || run(weak, interval, stop_thread));
+        Sweeper {
+            stop,
+            handle: Some(handle),
+        }
+    }
+}
+
+/// Laço da thread: dorme `interval` (em fatias) e então varre os expirados,
+/// repetindo até receber o sinal de parada ou o cache deixar de existir.
+fn run(cache: Weak<RustCache>, interval: Duration, stop: Arc<AtomicBool>) {
+    let tick = Duration::from_millis(200);
+    loop {
+        let mut waited = Duration::ZERO;
+        while waited < interval {
+            if stop.load(Ordering::Relaxed) {
+                return;
+            }
+            let chunk = tick.min(interval - waited);
+            thread::sleep(chunk);
+            waited += chunk;
+        }
+        if stop.load(Ordering::Relaxed) {
+            return;
+        }
+        match cache.upgrade() {
+            Some(c) => {
+                c.cleanup_expired(now_ms());
+            }
+            None => return, // o cache foi coletado; nada mais a varrer
+        }
+    }
+}
+
+impl Drop for Sweeper {
+    fn drop(&mut self) {
+        self.stop.store(true, Ordering::Relaxed);
+        if let Some(handle) = self.handle.take() {
+            let _ = handle.join();
+        }
+    }
+}

rust_py_cache-0.2.0/tests/test_eviction.py

@@ -0,0 +1,79 @@
+"""Eviction (LRU) + expiração em background.
+
+A correção da LRU "qual chave sai" é verificada de forma determinística nos
+testes Rust (`src/cache.rs`), onde o relógio é injetado. Aqui cobrimos a API
+Python: seleção de política, o getter `eviction_policy`, validação, retorno de
+`set` e a thread de expiração em background.
+"""
+
+import time
+
+import pytest
+
+from rust_py_cache import Cache
+
+
+def test_eviction_policy_defaults_to_reject():
+    cache = Cache(max_size=2)
+    assert cache.eviction_policy == "reject"
+
+
+def test_eviction_policy_getter_reports_lru():
+    cache = Cache(max_size=2, eviction_policy="lru")
+    assert cache.eviction_policy == "lru"
+
+
+def test_invalid_eviction_policy_raises():
+    with pytest.raises(ValueError):
+        Cache(max_size=2, eviction_policy="lfu")
+
+
+def test_reject_blocks_new_keys_when_full():
+    cache = Cache(max_size=2, eviction_policy="reject")
+    assert cache.set("a", 1) is True
+    assert cache.set("b", 2) is True
+    assert cache.set("c", 3) is False  # cheio
+    assert len(cache) == 2
+    assert cache.stats()["evicted"] == 0
+    # sobrescrever chave existente continua permitido
+    assert cache.set("a", 10) is True
+
+
+def test_lru_evicts_to_make_room():
+    cache = Cache(max_size=2, eviction_policy="lru")
+    cache.set("a", 1)
+    cache.set("b", 2)
+    cache.set("c", 3)  # cheio + chave nova => remove a LRU
+    assert len(cache) == 2
+    assert cache.stats()["evicted"] == 1
+
+
+def test_lru_keeps_recently_used():
+    cache = Cache(max_size=2, eviction_policy="lru")
+    cache.set("a", 1)
+    cache.set("b", 2)
+    time.sleep(0.01)
+    assert cache.get("a") == 1  # "b" passa a ser a menos recentemente usada
+    cache.set("c", 3)
+    assert cache.get("b") is None  # evicted
+    assert cache.get("a") == 1
+    assert cache.get("c") == 3
+
+
+def test_no_max_size_never_evicts():
+    cache = Cache()
+    for i in range(100):
+        cache.set(f"k{i}", i)
+    assert len(cache) == 100
+    assert cache.stats()["evicted"] == 0
+
+
+def test_background_expiration_sweeps_automatically():
+    cache = Cache(cleanup_interval=0.5)
+    cache.set("a", 1, ttl=0.5)
+    assert len(cache) == 1
+    # Sem chamar cleanup_expired(): a thread de fundo deve coletar depois que o
+    # TTL (0.5s) vence e o sweeper (0.5s) roda.
+    time.sleep(1.6)
+    assert len(cache) == 0
+    assert cache.stats()["expired"] >= 1

{rust_py_cache-0.1.2 → rust_py_cache-0.2.0}/tests/test_features.py

@@ -56,7 +56,15 @@ def test_stats_tracks_operations():
     assert s["misses"] == 1
     assert s["deletes"] == 1
     assert s["size"] == 0
-    assert set(s) == {"hits", "misses", "sets", "deletes", "expired", "size"}
+    assert set(s) == {
+        "hits",
+        "misses",
+        "sets",
+        "deletes",
+        "expired",
+        "evicted",
+        "size",
+    }
 
 
 def test_decorator_caches_calls():