# TS_STL **Repository Path**: C-Qiyao/TS_STL ## Basic Information - **Project Name**: TS_STL - **Description**: This is a high-performance, easy-to-use, thread-safe STL container proxy library. It provides an elegant template framework for creating thread-safe STL containers and supports three synchronization mechanisms: mutex, read-write lock, and spinlock.这是一个高性能、易用的线程安全STL容器代理库。提供了一个优雅的模板框架，用于创建线程安全的STL容器，支持互斥锁、读写锁、自旋锁三种同步机制。 - **Primary Language**: C++ - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-20 - **Last Updated**: 2025-11-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Thread-Safe STL (TS_STL) 库 **[English README](README.md)** 这是一个高性能、易用的线程安全STL容器代理库。提供了一个优雅的模板框架（Head-only），用于创建线程安全的STL容器，支持互斥锁、读写锁、自旋锁三种同步机制。 ## 📋 特性概览 ### 核心特性 - ✅ **四锁策略**: 互斥锁、读写锁、自旋锁和无锁，可在初始化时选择 - ✅ **自动同步**: 所有关键操作自动线程安全，无需手动加锁 - ✅ **STL兼容**: 支持隐式转换到标准容器，与STL算法库兼容 - ✅ **零开销抽象**: 编译时多态（CRTP），不使用的代码路径被完全优化掉 - ✅ **异常安全**: RAII模式确保异常情况下的安全性 - ✅ **丰富API**: operator[]、get/set接口、迭代、查找、容量管理等 - ✅ **高性能**: 最小化锁粒度，支持移动语义 - ✅ **易于扩展**: 使用 CRTP 减少代码重复，添加新容器只需最少代码 ### 实现特性 - 🔒 互斥锁（Mutex）: 简洁高效，适合通用场景 - 🔐 读写锁（ReadWrite）: 允许并发读，适合读密集型应用 - 🔄 自旋锁（SpinLock）: 极低延迟，适合短临界区 - ⚡ 无锁（LockFree）: 零开销，极限性能，需要外部同步 - 📦 RAII模式: 自动锁管理 - 🎯 编译时条件: 零成本的策略选择 - 🛡️ 异常处理: 完整的异常安全保证 - 🏗️ CRTP设计: 静态多态，消除代码重复 ### 支持的容器 | 容器 | 类名 | 类型别名 | 特点 | |------|------|---------|------| | `std::vector` | `vector` | `vectorMutex` / `vectorRW` | 随机访问，动态数组 | | `std::list` | `list` | `listMutex` / `listRW` | 双向链表，高效插删 | | `std::map` | `map` | `mapMutex` / `mapRW` | 有序键值对，快速查找 | | `std::unordered_map` | `unordered_map` | `unordered_mapMutex` | 哈希表，O(1)查找 | | `std::set` | `set` | `setMutex` | 有序唯一元素 | | `std::unordered_set` | `unordered_set` | `unordered_setMutex` | 哈希表，O(1)查找 | | `std::deque` | `deque` | `dequeMutex` | 双端队列，两端高效 | ### 🔴 多线程安全性对比 | 测试 | TS_STL | STD 容器 | |------|--------|----------| | 单线程写入 | ✅ 100% 正确 | ✅ 100% 正确 | | **并发写入** | ✅ **100% 正确** | ❌ **CRASH** | | **并发读取** | ✅ **100% 正确** | ❌ **线程不安全** | | **混合读写** | ✅ **100% 正确** | ❌ **CRASH** | > ⚠️ **重要**: STD 容器在多线程环境下会导致程序崩溃！ ### 并发读写性能建议速查 ``` ✅ 选择 vectorMutex → 通用最佳，所有场景稳定高效 ✅ 选择 vectorLockFree → 单线程初始化，零开销(100%性能) ⚠️ 谨慎 vectorRW → 读写锁优势未明显体现 ⚠️ 避免 vectorSpinLock → 高并发竞争场景性能差(仅20%) ❌ 多线程不要用 std::vector → 线程不安全会崩溃 ``` **性能数据**: - `vectorLockFree` 单线程性能 = std::vector 的 100%（零开销） - `vectorMutex` 多线程性能 = std::vector+mutex 的 79-87%（安全+易用） ### 🎯 数据准确性验证 | 锁类型 | 单线程 | 并发写 | 并发读 | 90%读10%写 | 50%读50%写 | 大对象 | 总体 | |--------|--------|--------|--------|-----------|-----------|--------|------| | **Mutex** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 6/6 | | **SpinLock** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 6/6 | | **RW-Lock** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 6/6 | | **STD Vector** | ✅ | ❌ CRASH | ❌ UNSAFE | ❌ CRASH | ❌ CRASH | - | ❌ 0/6 | **结论**: - ✅ **TS_STL 在所有 6 个场景都 100% 正确 (18/18 测试通过)** - ❌ **STD 容器在多线程环境下完全不安全** ## 性能测试结果 ### Concurrent Read | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | std::vector+mutex | 20.45 | 1200000 | 58672 | 100.0% | ✓ | | vectorMutex | 23.46 | 1200000 | 51152 | 87.2% | ✓ | | vectorSpinLock | 284.53 | 1200000 | 4218 | 7.2% | ✓ | | vectorRW | 113.14 | 1200000 | 10606 | 18.1% | ✓ | ### Concurrent Write | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | std::vector+mutex | 16.80 | 800000 | 47611 | 100.0% | ✓ | | vectorMutex | 20.44 | 800000 | 39143 | 82.2% | ✓ | | vectorSpinLock | 234.15 | 800000 | 3417 | 7.2% | ✓ | | vectorRW | 87.90 | 800000 | 9101 | 19.1% | ✓ | ### Mixed R/W (50:50) | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | std::vector+mutex | 12.69 | 800000 | 63037 | 100.0% | ✓ | | vectorMutex | 15.98 | 800000 | 50075 | 79.4% | ✓ | | vectorSpinLock | 149.89 | 800000 | 5337 | 8.5% | ✓ | | vectorRW | 97.37 | 800000 | 8216 | 13.0% | ✓ | ### Mixed R/W (90:10) | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | std::vector+mutex | 15.92 | 1000000 | 62812 | 100.0% | ✓ | | vectorMutex | 19.83 | 1000000 | 50441 | 80.3% | ✓ | | vectorSpinLock | 185.57 | 1000000 | 5389 | 8.6% | ✓ | | vectorRW | 112.56 | 1000000 | 8884 | 14.1% | ✓ | ### Single Thread Push Back | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | std::vector | 2.22 | 1000000 | 449800 | 100.0% | ✓ | | vectorMutex | 6.68 | 1000000 | 149720 | 33.3% | ✓ | | vectorSpinLock | 3.98 | 1000000 | 251317 | 55.9% | ✓ | | vectorLockFree | 2.24 | 1000000 | 446778 | 99.3% | ✓ | | vectorRW | 13.36 | 1000000 | 74824 | 16.6% | ✓ | ### Map Concurrent Insert | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | mapMutex | 1852.94 | 80000 | 43 | 100.0% | ✓ | | mapRW | 2507.65 | 80000 | 32 | 73.9% | ✓ | ### Map Concurrent Read | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | mapMutex | 60.15 | 1200000 | 19951 | 100.0% | ✓ | | mapRW | 98.54 | 1200000 | 12178 | 61.0% | ✓ | ### Map Single Thread Insert | 容器类型 | 耗时(ms) | 操作数 | 吞吐量(ops/ms) | 相对性能 | 数据正确 | |---------|---------|--------|---------------|---------|----------| | mapMutex | 124.77 | 10000 | 80 | 97.3% | ✓ | | mapRW | 121.34 | 10000 | 82 | 100.0% | ✓ | ### 性能使用建议 ``` 场景推荐容器 ---------------------- --------------------------- 单线程/初始化 vectorLockFree (零开销) 多线程并发写入 vectorMutex or vectorSpinLock 多线程并发读取 vectorRW (读写锁优势明显) 读多写少(90:10) vectorRW (读写锁最优) 读写均衡(50:50) vectorMutex (通用稳定) 高竞争场景避免 vectorSpinLock ``` --- ### Vector 特性 ```cpp #include "ts_stl.hpp" // 创建线程安全的向量（默认使用互斥锁） ts_stl::vectorMutex vec; // 使用就像标准vector一样 vec.push_back(1); vec.push_back(2); vec[0] = 10; // 线程安全的数组风格访问 std::cout << vec.size(); // 线程安全的查询 ``` ### List 特性 ```cpp #include "ts_stl.hpp" // 创建线程安全的链表 ts_stl::listMutex list; // 支持list特有操作 list.push_back(1); list.push_front(0); list.sort(); // 排序 list.reverse(); // 反转 list.remove(1); // 删除指定值 ``` ### Map 特性 ```cpp #include "ts_stl.hpp" // 创建线程安全的字典 ts_stl::mapMutex scores; // 插入和查询 scores.insert("Alice", 90); scores.set("Bob", 85); // 获取值（支持默认值） int score = scores.get("Alice"); int missing = scores.get("Charlie", -1); // 不存在返回-1 // 检查存在性 if (scores.contains("Alice")) { std::cout << "Alice found!" << std::endl; } // 遍历 scores.for_each([](const auto& key, const auto& value) { std::cout << key << ": " << value << std::endl; }); // 删除 scores.erase("Bob"); // 条件统计 int high_scores = scores.count_if([](const auto& key, const auto& value) { return value >= 80; }); ``` ### operator[] vs get/set - 选择指南 | 方法 | 用途 | 边界检查 | 推荐场景 | |------|------|---------|---------| | `vec[i]` | 快速读写 | ❌ 无 | 已验证索引的紧密循环 | | `vec.get(i)` | 仅读取 | ❌ 无 | 并发多读场景 | | `vec.set(i, val)` | 仅写入 | ❌ 无 | 原语意清晰的更新 | | `vec.at(i)` | 安全读写 | ✅ 有 | 不信任索引来源的代码 | ```cpp // 性能敏感的紧密循环 - 用 operator[] for (size_t i = 0; i < vec.size(); ++i) { total += vec[i]; // 快速，无检查开销 } // 需要安全性 - 用 at() try { std::cout << vec.at(100); // 自动检查越界 } catch (const std::out_of_range& e) { std::cerr << "Error: " << e.what() << std::endl; } ``` ### 对象初始化 - 选择锁策略 #### 方式1️⃣: 使用便利类型别名（推荐） ```cpp // 互斥锁版本 - 通用、高效 vectorMutex mutex_vec; mutex_vec.push_back(1); mutex_vec.push_back(2); // 读写锁版本 - 适合读多写少的场景（C++17+） vectorRW rw_vec; rw_vec.push_back("hello"); rw_vec.push_back("world"); // 无锁版本 - 极限性能，单线程初始化阶段 ⚡ vectorLockFree lockfree_vec; for (int i = 0; i < 1000000; ++i) { lockfree_vec.push_back(i); // 零锁开销！ } ``` #### 方式2️⃣: 显式指定锁策略模板参数 ```cpp // 互斥锁（明确指定） vector explicit_mutex; explicit_mutex.push_back(100); // 无锁策略（明确指定 - 需要外部同步） vector explicit_lockfree; explicit_lockfree.push_back(100); // 读写锁（明确指定，仅C++17+） #if TS_STL_SUPPORT_RW_LOCK vector explicit_rw; explicit_rw.push_back(200); #endif ``` #### 方式3️⃣: 默认初始化 ```cpp // 默认使用互斥锁 vector default_vec; default_vec.push_back(3.14); ``` #### 方式4️⃣: 构造时传入初始数据 ```cpp // 创建包含初始元素的向量 vectorMutex initialized_vec(5); // 5个默认元素 vectorMutex filled_vec(5, 42); // 5个值为42的元素 // 使用迭代器范围初始化 std::vector init_data = {1, 2, 3, 4, 5}; vectorMutex from_range(init_data.begin(), init_data.end()); ``` ### Vector 多线程操作 ```cpp vectorMutex shared_vec; // 多个线程可以安全地同时访问 std::vector threads; for (int i = 0; i < 4; ++i) { threads.emplace_back([&shared_vec, i]() { for (int j = 0; j < 100; ++j) { shared_vec.push_back(i * 100 + j); // 自动线程安全！ } }); } for (auto& t : threads) { t.join(); } // 现在有 400 个元素，完全没有竞态条件 ``` ### List 多线程操作 ```cpp listMutex shared_list; // 多线程安全地添加元素 std::vector threads; for (int i = 0; i < 4; ++i) { threads.emplace_back([&shared_list, i]() { for (int j = 0; j < 50; ++j) { // 既可以从末尾添加 if (i % 2 == 0) { shared_list.push_back(i * 50 + j); } else { // 也可以从首部添加 shared_list.push_front(i * 50 + j); } } }); } for (auto& t : threads) { t.join(); } // 排序和处理 shared_list.sort(); shared_list.remove_if([](int x) { return x % 10 == 0; }); ``` ### Map 多线程操作 ```cpp mapMutex cache; // 多线程安全地更新缓存 std::vector threads; for (int i = 0; i < 4; ++i) { threads.emplace_back([&cache, i]() { for (int j = 0; j < 100; ++j) { std::string key = "key_" + std::to_string(i * 100 + j); cache.insert(key, i * 100 + j); } }); } for (auto& t : threads) { t.join(); } // 多线程读取（使用读写锁可以加速） mapRW read_cache; // ... 初始化数据 ... std::vector readers; for (int i = 0; i < 8; ++i) { // 8个读线程 readers.emplace_back([&read_cache]() { for (int j = 0; j < 1000; ++j) { std::string key = "key_" + std::to_string(j); int value = read_cache.get(key, -1); // 线程安全的读取 } }); } for (auto& t : readers) { t.join(); } // 遍历缓存中的所有项 cache.for_each([](const auto& key, const auto& value) { std::cout << key << " -> " << value << std::endl; }); ``` | 场景 | 推荐方案 | 用法 | |------|---------|------| | 通用、读写均衡 | **互斥锁** | `vectorMutex` | | 读操作远多于写 | **读写锁** (C++17+) | `vectorRW` | | 不确定选择 | **互斥锁** | `vector` | | 需要最大兼容性 | **互斥锁** | C++11/14 下自动选择 | ### Vector 元素访问 ```cpp vec[index] // ✨ 新增：数组风格访问（线程安全，无边界检查） vec.get(index) // 获取元素（线程安全，等价于 operator[]） vec.set(index, value) // 设置元素（线程安全） vec.at(index) // 安全访问（带边界检查） vec.front() // 获取首元素 vec.back() // 获取末尾元素 ``` ### List 元素访问 ```cpp list.front() // 获取首元素 list.back() // 获取末尾元素 list.set_front(value) // 设置首元素 list.set_back(value) // 设置末尾元素 ``` ### Map 元素访问 ```cpp map[key] // 获取/插入元素（线程安全） map.get(key) // 获取元素（不存在返回默认值） map.get(key, default_val) // 获取元素，指定默认值 map.set(key, value) // 设置元素 map.at(key) // 安全访问（带边界检查） map.contains(key) // 检查键是否存在 map.count(key) // 计数（0 或 1） map.count_if(predicate) // 条件计数 map.insert(key, value) // 插入元素 map.erase(key) // 删除元素 map.find_if(predicate) // 条件查找 ``` ### Unordered Map 元素访问 ```cpp umap[key] // 获取/插入元素（线程安全） umap.get(key) // 获取元素（不存在返回默认值） umap.get(key, default_val) // 获取元素，指定默认值 umap.set(key, value) // 设置元素 umap.at(key) // 安全访问（带边界检查） umap.contains(key) // 检查键是否存在 umap.count(key) // 计数（0 或 1） umap.count_if(predicate) // 条件计数 umap.insert(key, value) // 插入元素 umap.erase(key) // 删除元素 umap.find_if(predicate) // 条件查找 umap.bucket_count() // 获取桶数量 umap.load_factor() // 获取装载因子 umap.reserve(n) // 预留n个元素的空间 umap.rehash(n) // 重新哈希至少为n个桶 ``` ### 通用容量管理（Vector & List & Map & Unordered Map） ```cpp vec.size() // 获取大小 vec.capacity() // 获取容量（Vector） vec.empty() // 检查是否为空 vec.reserve(count) // 预留空间（Vector & Unordered Map） vec.resize(count) // 改变大小 vec.shrink_to_fit() // 收缩到实际大小（Vector） map.clear() // 清空容器 ``` ### Vector 特定操作 ```cpp vec.push_back(value) // 添加元素 vec.pop_back() // 移除末尾元素 vec.emplace_back(args...) // 原地构造 vec.insert(pos, value) // 插入 vec.erase(pos) // 删除 ``` ### List 特定操作 ```cpp list.push_back(value) // 添加到末尾 list.pop_back() // 移除末尾元素 list.push_front(value) // 添加到首部 list.pop_front() // 移除首部元素 list.emplace_back(args...) // 原地构造 list.emplace_front(args...) // 首部原地构造 list.remove(value) // 移除所有值为value的元素 list.remove_if(predicate) // 移除满足条件的元素 list.reverse() // 反转列表 list.sort() // 排序列表 ``` ### Map 特定操作 ```cpp map.insert(key, value) // 插入元素（返回 pair） map.emplace(key, ...) // 原地构造 map.erase(key) // 删除元素 map.for_each(func) // 遍历（func(key, value)） map.count_if(predicate) // 条件计数 map.find_if(predicate) // 条件查找 ``` ### Set 元素访问 ```cpp set.insert(element) // 插入元素（返回 pair） set.erase(element) // 删除元素 set.contains(element) // 检查元素是否存在 set.count(element) // 计数（0 或 1） set.count_if(predicate) // 条件计数 set.find_if(predicate) // 条件查找 set.for_each(func) // 遍历所有元素 set.clear() // 清空集合 ``` ### Unordered Set 元素访问 ```cpp uset.insert(element) // 插入元素（返回 pair） uset.erase(element) // 删除元素 uset.contains(element) // 检查元素是否存在 uset.count(element) // 计数（0 或 1） uset.count_if(predicate) // 条件计数 uset.find_if(predicate) // 条件查找 uset.bucket_count() // 获取哈希桶个数 uset.load_factor() // 获取负载因子 uset.reserve(n) // 为n个元素预留空间 uset.rehash(n) // 重新哈希为至少n个桶 uset.for_each(func) // 遍历所有元素 uset.clear() // 清空集合 ``` ### Deque 元素访问 ```cpp dq.push_back(value) // 从末尾添加 dq.pop_back() // 从末尾移除 dq.push_front(value) // 从首部添加 dq.pop_front() // 从首部移除 dq.emplace_back(args...) // 末尾原地构造 dq.emplace_front(args...) // 首部原地构造 dq.front() // 获取首元素 dq.back() // 获取末元素 dq.at(index) // 安全访问（带边界检查） dq.size() // 获取大小 dq.empty() // 检查是否为空 dq.clear() // 清空双端队列 dq.for_each(func) // 遍历所有元素 dq.count_if(predicate) // 条件计数 ``` ```cpp // 隐式转换到 const std::vector& const std::vector& std_ref = ts_vec; // 获取副本 std::vector copy = ts_vec.to_vector(); // 支持标准算法 std::for_each(std_ref.begin(), std_ref.end(), [](int x) { std::cout << x << " "; }); ``` ### 迭代和查询 ```cpp vec.for_each([](const T& item) { /* process */ }); vec.find_if([](const T& item) { return item > 10; }); vec.contains(value) // 检查是否包含 ``` ## 🏗️ 项目结构 ``` TS_STL/ ├── include/ │ ├── ts_stl.hpp # 核心库头文件（包含所有容器） │ ├── ts_vector.hpp # 线程安全vector实现 │ ├── ts_list.hpp # 线程安全list实现 │ ├── ts_map.hpp # 线程安全map实现 │ ├── ts_unordered_map.hpp # 线程安全unordered_map实现 │ ├── ts_set.hpp # 线程安全set实现（新增） │ ├── ts_unordered_set.hpp # 线程安全unordered_set实现（新增） │ ├── ts_deque.hpp # 线程安全deque实现（新增） │ └── ts_stl_base.hpp # 基类和锁策略 ├── test/ │ ├── test_thread_safe_vector.cpp # Vector测试 │ ├── test_thread_safe_list.cpp # List测试 │ ├── test_unordered_map.cpp # Unordered map测试 │ └── test_new_containers.cpp # Set/Unordered Set/Deque测试（新增） ├── examples/ │ ├── example_usage.cpp # Vector使用示例 │ ├── example_map_usage.cpp # Map使用示例 │ ├── example_unordered_map_usage.cpp # Unordered map使用示例 │ └── example_new_containers.cpp # Set/Unordered Set/Deque示例（新增） ├── CMakeLists.txt # CMake构建配置 ├── USAGE_GUIDE.md # 详细使用指南 ├── docs/ │ └── ARCHITECTURE.md # 架构文档 └── README.md # 本文件 ``` ## 📦 编译和运行 ### 使用CMake（推荐） ```bash # 创建构建目录 mkdir build cd build # 配置和编译 cmake .. cmake --build . # 运行单元测试 ./test_thread_safe_vector # 运行示例 ./example_usage # 🎯 运行综合性能测试（包含std::vector对比） ./comprehensive_performance_test ``` ### 手动编译 ```bash # 编译测试（需要C++17及以上） clang++ -std=c++17 -pthread -I./include \ test/test_thread_safe_vector.cpp -o test # 运行 ./test # 编译综合性能测试 clang++ -std=c++17 -O3 -pthread -I./include \ examples/comprehensive_performance_test.cpp -o comprehensive_perf # 运行性能测试 ./comprehensive_perf ``` ## ✅ 测试覆盖库包含全面的测试套件（3个测试文件，35+个测试用例）： ### ThreadSafeVector 测试（10个测试组） - ✓ 基本操作 (push_back, get, set, etc.) - ✓ 容量管理 (resize, reserve, clear) - ✓ 拷贝和移动语义 - ✓ 多线程并发访问 - ✓ 读写锁策略验证 - ✓ emplace_back 原地构造 - ✓ 隐式转换到std::vector - ✓ 迭代和查找操作 - ✓ 异常处理安全性 - ✓ 两种锁策略对比 ### ThreadSafeList 测试（10个测试组） - ✓ 基本操作 (push_back, front, back) - ✓ 首部操作 (push_front, pop_front, emplace_front) - ✓ 移除操作 (remove, remove_if, clear) - ✓ 排序和反转 - ✓ 查询操作 (contains, count, for_each) - ✓ 拷贝和移动语义 - ✓ 多线程并发访问 - ✓ 手动锁控制 - ✓ 复杂数据类型 - ✓ 列表特定操作 ### 高级功能测试（5个测试组） - ✓ 线程不安全接口性能 - ✓ 手动锁控制 - ✓ 读锁接口（C++17+） - ✓ 复杂场景 - ✓ 性能对比 ## �� 锁策略选择指南 ### 使用互斥锁（Mutex）： - ✅ 读写操作均衡 - ✅ 对低延迟敏感 - ✅ 简单的线程协调 - ✅ 缓存性能重要 ### 使用读写锁（ReadWrite）： - ✅ 缓存系统（大量读，少量写） - ✅ 配置管理（读远多于写） - ✅ 统计收集 - ✅ 只读数据库访问 ## 🎯 设计原则 1. **最小化锁粒度**: 仅在必要时加锁 2. **零成本抽象**: 编译时多态，无运行时开销 3. **RAII安全**: 异常安全的资源管理 4. **STL兼容**: 与标准库无缝集成 5. **易用性**: 简洁直观的API ## ⚡ 性能特点 - **互斥锁版本**: 最快，适合通用场景 - **读写锁版本**: 读操作快，写操作略慢 - **编译时优化**: 零开销的策略选择 - **移动语义支持**: 减少不必要的复制 ## 📊 性能基准测试我们提供了全面的性能基准测试程序，对比 TS_STL 与标准 STL 容器的性能。 ### 运行性能测试 ```bash cd build ./performance_benchmark ``` ### 性能分析 #### 单线程性能 - **Vector 顺序插入**: +96% 开销（锁初始化和检查成本） - **Vector 随机访问**: +41% 开销（虽然有锁开销，但缓存友好性相近） - **List 操作**: +33% 开销（链表结构相对开销较小） #### 多线程性能 - **并发写入**: 仅 +25% 开销（手动锁定成本相近） - **并发读取（RW锁）**: TS_STL 快得多（得益于细粒度锁策略） - **混合操作**: +86% 开销（取决于读写比例） ### 关键发现 1. **单线程场景**：单线程使用时，有一定的锁初始化开销（5-40%） - 解决方案：使用 `unsafe_*` 接口获得零开销 - 或使用 `with_write_lock()` 批量操作 2. **多线程场景**：在多线程环境下，TS_STL 往往表现更好 - 自动锁管理减少了手动错误 - 读写锁提供显著优化（并发读取性能提升） 3. **读密集型工作负载**：读写锁 (`vectorRW`) 显著优于互斥锁 - 并发读操作可以完全并行 - 极大减少了锁争竞 ### 优化建议 **当需要极致性能时：** ```cpp // ✅ 方式1: 使用 unsafe 接口（需确保外部同步） vectorMutex vec; { auto guard = vec.acquire_write_guard(); for (int i = 0; i < N; ++i) { vec.unsafe_ref().push_back(i); // 直接访问，无额外开销 } } // ✅ 方式2: 批量操作 vector vec; vec.with_write_lock([](auto& v) { for (int i = 0; i < N; ++i) { v.unsafe_ref().push_back(i); // 一次性加锁 } }); // ✅ 方式3: 单线程初始化 → 多线程读取 vector vec; // 单线程初始化完成 for (int i = 0; i < N; ++i) { vec.push_back(i); // 单线程时有开销 } // 现在多线程只进行读取操作 ``` ## 🔐 线程安全保证 - **基本异常保证**: 异常后容器处于有效状态 - **强异常保证**: 多数操作要么完全成功要么完全失败 - **无异常操作**: 移动操作标记为noexcept ## 📋 注意事项 1. **指针有效性**: `data()` 返回的指针可能因其他线程的操作而失效 2. **迭代器**: 在多线程环境中，传统迭代器不适用，改用 `for_each()` 或 `to_vector()` 3. **死锁风险**: 在回调函数中再次调用容器方法可能导致死锁 4. **原子性**: 单个操作是原子的，但多操作序列可能需要额外同步 ## 📄 许可证 MIT License - 自由使用和修改 --- **快速链接：** - [详细使用指南](USAGE_GUIDE.md) - [完整API文档](include/ts_stl.hpp) (代码中有详细注释) - [测试代码](test/test_thread_safe_vector.cpp) - [使用示例](examples/example_usage.cpp) ## 🆕 高级功能（新增） ### 对象初始化详解 #### 基础初始化方式对比 ```cpp // ❶ 默认构造（推荐简洁用法） vector vec1; // 自动使用互斥锁 // ❷ 使用类型别名（最常用） vectorMutex vec2; // 互斥锁版本 vectorRW vec3; // 读写锁版本（C++17+） // ❸ 显式模板参数（明确指定） vector vec4; #if TS_STL_SUPPORT_RW_LOCK vector vec5; // C++17+ 可用 #endif // ❹ 带初始值的构造 vectorMutex vec6(10); // 10个默认元素 vectorMutex vec7(10, 42); // 10个值为42的元素 // ❺ 从其他容器初始化 std::vector source = {1, 2, 3, 4, 5}; vectorMutex vec8(source.begin(), source.end()); // ❻ 复杂数据类型初始化 struct User { std::string name; int age; }; vectorRW users; // 用于多读少写的场景 users.push_back({"Alice", 25}); users.push_back({"Bob", 30}); ``` #### 不同场景的初始化选择 ```cpp // 场景1: 通用缓冲区 → 互斥锁 vectorMutex log_buffer; log_buffer.push_back("event 1"); // 场景2: 配置数据（读多写少） → 读写锁 vectorRW config; config.push_back(Config{...}); // 场景3: 性能关键代码 → 互斥锁 + 高级接口 vectorMutex data(1000); // 预留1000元素 data.reserve(2000); // 场景4: 兼容旧代码 → 默认构造 vector legacy; // 自动选择互斥锁 ``` ### 线程不安全接口提供零开销的 `unsafe_*` 接口，用于在已获取锁或单线程环境下进行极致优化。 ### 手动锁控制 - `acquire_write_guard()` - 获取写锁 - `with_write_lock()` - 在写锁保护下执行代码块 - `acquire_read_guard()` (C++17+) - 获取读锁 - `with_read_lock()` (C++17+) - 在读锁保护下执行代码块 ### C++ 版本条件编译 - C++17+: 完整功能（互斥锁 + 读写锁 + 自旋锁） - C++<17: 基础功能（仅互斥锁 + 自旋锁） --- **快速链接：** - [详细使用指南](docs/USAGE_GUIDE.md) - [完整API文档](include/ts_stl.hpp) (代码中有详细注释) - [测试代码](test/test_thread_safe_vector.cpp) - [高级功能测试](test/test_advanced_features.cpp) - [使用示例](examples/example_usage.cpp)