refactor: 升级至 1.1.0，统一无锁原子核心并修复 Windows 序列化问题

- 重构 C++ 后端：移除自旋锁，统一采用 std::atomic 无锁实现，提升并发性能。
- 修复 Windows 下的 PicklingError：引入 CachetoolsDecorator 支持 spawn 模式下的缓存序列化。
- 简化 API：提供智能工厂方法 get_opt_cache，自动处理单/多进程后端路由。
- 同步 lab 脚本：更新所有实验脚本以适配 1.1.0 API，修复语法分析器警告。
- 文档更新：同步 README 示例并清理过时的实验文件。

Author: Puiching-Memory

README.md

@@ -39,35 +39,39 @@ pip install OPT4TorchDataset
 
 ## Quick Start
 
-### Method 1: API
+### Method 1: Using get_opt_cache (Recommended)
 
 ```python
-from OPT4TorchDataSet.cachelib import generate_precomputed_file, OPTCacheDecorator
+from OPT4TorchDataSet import generate_precomputed_file, get_opt_cache
 from torch.utils.data import DataLoader
 
 # Step 1: Offline generation of precomputed file (one-time)
 generate_precomputed_file(
     dataset_size=10000,
     total_iterations=100000,
-    persist_path="precomputed/my_experiment.safetensors",
+    persist_path="precomputed/my_plan.safetensors",
     random_seed=0,
-    replacement=True,
     maxsize=3000
 )
 
-# Step 2: Create cache decorator at runtime
-decorator = OPTCacheDecorator(
-    precomputed_path="precomputed/my_experiment.safetensors",
-    maxsize=3000, # Must be consistent with maxsize during precomputation
-    total_iter=100000
+# Step 2: Create cache decorator (Intelligent mode: auto-handles single/multi-process)
+# num_workers=0 automatically uses high-performance Python version
+# num_workers>0 automatically uses Shared Memory C++ version
+dataset = MyDataset()
+dataset.cache = get_opt_cache(
+    num_workers=0,
+    precomputed_path="precomputed/my_plan.safetensors",
+    maxsize=3000,
+    total_iter=100000,           # Required for Python mode
+    dataset_size=10000,          # Required for Shared Memory (C++) mode
+    item_shape=(3, 224, 224)    # Required for Shared Memory (C++) mode
 )
 
 # Step 3: Apply to dataset
-dataset = MyDataset()
-dataset.__getitem__ = decorator(dataset.__getitem__)
+dataset.__getitem__ = dataset.cache(dataset.__getitem__)
 
 # Use DataLoader
-dataloader = DataLoader(dataset, batch_size=32)
+dataloader = DataLoader(dataset, batch_size=32, num_workers=0)
 for batch in dataloader:
     pass
 ```

README_zh.md

@@ -39,35 +39,39 @@ pip install OPT4TorchDataset
 
 ## Quick Start
 
-### Method 1: API
+### Method 1: 使用 get_opt_cache (推荐)
 
 ```python
-from OPT4TorchDataSet.cachelib import generate_precomputed_file, OPTCacheDecorator
+from OPT4TorchDataSet import generate_precomputed_file, get_opt_cache
 from torch.utils.data import DataLoader
 
 # Step 1: 离线生成预计算文件（一次性）
 generate_precomputed_file(
     dataset_size=10000,
     total_iterations=100000,
-    persist_path="precomputed/my_experiment.safetensors",
+    persist_path="precomputed/my_plan.safetensors",
     random_seed=0,
-    replacement=True,
     maxsize=3000
 )
 
-# Step 2: 运行时创建缓存装饰器
-decorator = OPTCacheDecorator(
-    precomputed_path="precomputed/my_experiment.safetensors",
-    maxsize=3000, # 必须与预计算时的maxsize一致
-    total_iter=100000
+# Step 2: 运行时创建缓存装饰器（智能模式：自动处理单进程/多进程）
+# num_workers=0 会自动使用高性能 Python 版
+# num_workers>0 会自动使用共享内存 C++ 版
+dataset = MyDataset()
+dataset.cache = get_opt_cache(
+    num_workers=0,
+    precomputed_path="precomputed/my_plan.safetensors",
+    maxsize=3000,
+    total_iter=100000,           # Python 模式需要
+    dataset_size=10000,          # 共享内存 (C++) 模式需要
+    item_shape=(3, 224, 224)    # 共享内存 (C++) 模式需要
 )
 
 # Step 3: 应用到数据集
-dataset = MyDataset()
-dataset.__getitem__ = decorator(dataset.__getitem__)
+dataset.__getitem__ = dataset.cache(dataset.__getitem__)
 
 # 使用数据加载器
-dataloader = DataLoader(dataset, batch_size=32)
+dataloader = DataLoader(dataset, batch_size=32, num_workers=0)
 for batch in dataloader:
     pass
 ```

lab/hit_rate/experiment.py

@@ -9,13 +9,12 @@
 import json
 import sys
 from pathlib import Path
-from typing import List, Dict, Tuple, Optional, Union, Any
+from typing import List, Tuple, Optional, Union, Any
 
-import torch
 import typer
 from loguru import logger
 from torch.utils.data import DataLoader, RandomSampler
-from cachetools import cached, LRUCache, LFUCache, FIFOCache, RRCache
+from cachetools import LRUCache, LFUCache, FIFOCache, RRCache
 
 PROJECT_ROOT = Path(__file__).resolve().parents[2]
 if str(PROJECT_ROOT) not in sys.path:
@@ -24,10 +23,11 @@
     sys.path.insert(0, str(PROJECT_ROOT / "src"))
 
 from lib.hit_rate_dataset import HitRateDataset
+from OPT4TorchDataSet import get_opt_cache, generate_precomputed_file
 from OPT4TorchDataSet.cachelib import (
     OPTCacheDecorator,
+    SharedOPTCacheDecorator,
     CachetoolsDecorator,
-    generate_precomputed_file,
 )
 
 # Setup logging
@@ -41,11 +41,11 @@
 class CacheExperiment:
     def __init__(
         self,
-        caches: Optional[List[Tuple[str, float, Any]]] = None,
+        caches: List[Tuple[str, float, Any]],
         output_dir: Union[str, Path] = "results",
         batch_size: int = 32,
         num_workers: int = 0,
-        dataset: Optional[torch.utils.data.Dataset] = None,
+        dataset: Optional[HitRateDataset] = None,
         epochs: int = 1,
     ):
         """
@@ -78,9 +78,13 @@ def _run_single_experiment(self, cache) -> float:
         Returns:
             float: 未命中次数
         """
+        if self.caches is None:
+            raise ValueError("Caches list cannot be None")
+        if self.dataset is None:
+            raise ValueError("Dataset cannot be None")
 
         # 创建新的数据集实例，确保每次实验都从干净状态开始
-        dataset = HitRateDataset(len(self.dataset.dataset))
+        dataset = HitRateDataset(len(self.dataset))
         dataset.setCache(cache)
 
         dataloader = DataLoader(
@@ -104,13 +108,17 @@ def _run_single_experiment(self, cache) -> float:
 
     def run(self):
         """运行所有缓存实验并保存结果"""
+        if self.caches is None:
+            raise ValueError("Caches list cannot be None")
+        if self.dataset is None:
+            raise ValueError("Dataset cannot be None")
 
         logger.info("Starting Cache Performance Experiments")
         results = []
 
         for name, cache_size, cache in self.caches:
             # 对于OPT缓存，需要重置状态
-            if isinstance(cache, OPTCacheDecorator):
+            if isinstance(cache, (OPTCacheDecorator, SharedOPTCacheDecorator)):
                 cache.reset()
 
             miss_count = self._run_single_experiment(cache)
@@ -201,10 +209,12 @@ def main(
 
                 logger.info(f"预计算文件生成完成: {precomputed_path}")
 
-            opt_decorator = OPTCacheDecorator(
+            opt_decorator = get_opt_cache(
+                mode="python",
                 precomputed_path=precomputed_path,
                 maxsize=cache_size,
                 total_iter=total_iter,
+                num_workers=0,
             )
             caches.append(("OPT", size, opt_decorator))
 

lab/ram_usage/experiment.py

@@ -12,7 +12,6 @@
 from typing import List, Dict, Tuple, Optional, Union, Any
 from copy import deepcopy
 
-import torch
 import psutil
 import typer
 from loguru import logger
@@ -26,7 +25,7 @@
     sys.path.insert(0, str(PROJECT_ROOT / "src"))
 
 from lib.hit_rate_dataset import HitRateDataset
-from OPT4TorchDataSet.cachelib import OPTCacheDecorator, generate_precomputed_file
+from OPT4TorchDataSet import get_opt_cache, generate_precomputed_file
 
 # Setup logging
 OUTPUT_DIR = Path(__file__).parent / "results"
@@ -39,11 +38,11 @@
 class CacheExperiment:
     def __init__(
         self,
-        caches: Optional[List[Tuple[str, float, Any]]] = None,
+        caches: List[Tuple[str, float, Any]],
         output_dir: Union[str, Path] = "results",
         batch_size: int = 32,
         num_workers: int = 0,
-        dataset: Optional[torch.utils.data.Dataset] = None,
+        dataset: Optional[HitRateDataset] = None,
         epochs: int = 1,
     ):
         self.caches = caches
@@ -57,6 +56,8 @@ def __init__(
 
     def _run_single_experiment(self, cache) -> Dict:
         """Run single experiment focused on RAM usage"""
+        if self.dataset is None:
+            raise ValueError("Dataset cannot be None")
 
         # 强制进行垃圾回收以获得更准确的基线内存使用量
         gc.collect()
@@ -98,21 +99,24 @@ def _run_single_experiment(self, cache) -> Dict:
 
         # 获取缓存统计信息
         entry_count = 0
-        if hasattr(dataset, "_getitem_impl"):
-            if hasattr(dataset._getitem_impl, "__wrapped__"):
-                cache = getattr(dataset._getitem_impl, "__wrapped__", None)
-                if (
-                    cache
-                    and hasattr(cache, "cache")
-                    and hasattr(cache.cache, "__dict__")
-                ):
-                    entry_count = (
-                        len(cache.cache) if hasattr(cache.cache, "__len__") else 0
-                    )
-                elif (
-                    cache and hasattr(cache, "__dict__") and "_cache" in cache.__dict__
-                ):
-                    entry_count = len(cache._cache)
+        # Check both _wrapped_getitem (HitRateDataset) and generic __getitem__
+        target_func = getattr(dataset, "_wrapped_getitem", None)
+        if target_func and hasattr(target_func, "__wrapped__"):
+            cache_obj = getattr(target_func, "__wrapped__", None)
+            if (
+                cache_obj
+                and hasattr(cache_obj, "cache")
+                and hasattr(cache_obj.cache, "__dict__")
+            ):
+                entry_count = (
+                    len(cache_obj.cache) if hasattr(cache_obj.cache, "__len__") else 0
+                )
+            elif (
+                cache_obj
+                and hasattr(cache_obj, "__dict__")
+                and "_cache" in cache_obj.__dict__
+            ):
+                entry_count = len(cache_obj._cache)
 
         # 清理
         del dataloader
@@ -226,10 +230,12 @@ def main(
                 (
                     "OPT",
                     size,
-                    OPTCacheDecorator(
+                    get_opt_cache(
+                        mode="python",
                         precomputed_path=precomputed_path,
                         maxsize=cache_size,
                         total_iter=total_iter,
+                        num_workers=0,
                     ),
                 )
             )