线程池借用机制

[chejinge]

Pika快慢命令分离 - 线程池借用机制详细设计

文档信息

• 版本: 1.0
• 日期: 2025-11-30
• 作者: Pika开发团队

---

目录

1. 核心概念
2. 线程池借用机制
3. 键亲和性路由机制
4. 完整调度流程
5. 代码实现细节
6. 配置参数说明
7. 示例场景分析

---

1. 核心概念

1.1 什么是线程池借用？

定义: 当一个线程池负载过高（队列接近满）而另一个线程池负载较低（队列较空）时，高负载线程池的任务可以临时"借用"低负载线程池的资源来执行。

目的:

• 避免单个线程池过载导致的任务堆积
• 提高系统整体资源利用率
• 减少因队列满而拒绝请求的情况

约束:

• 必须保证同一key的命令顺序性
• 不能破坏命令语义的正确性
• 借用决策要考虑系统负载状态

1.2 什么是键亲和性？

定义: 相同key的所有操作必须由同一个线程池处理，以保证操作的顺序性。

为什么需要键亲和性？

反例（没有键亲和性）：
时间线: T1           T2           T3           T4
快池:   SET key=1 ──────────────▶ GET key   ──▶ 返回1（正确）
慢池:              INCR key ────────────────▶ key变成2

问题: 如果没有亲和性约束，同一个key的操作可能在不同线程池，
      导致执行顺序错乱，GET可能读到旧值

正例（有键亲和性）：
时间线: T1           T2           T3           T4
快池:   SET key=1 ──▶ INCR key ──▶ GET key   ──▶ 返回2（正确）
慢池:   （其他key操作）

保证: 同一key的操作始终在同一线程池，严格按时间顺序执行

---

2. 线程池借用机制

2.1 借用的触发条件

系统通过队列饱和度来判断是否需要借用：

队列饱和度 = 当前队列长度 / 最大队列长度

判断逻辑:
┌─────────────────────────────────────────────────────────┐
│ 条件1: 源线程池饱和度 >= 借用阈值（默认75%）            │
│ 条件2: 目标线程池饱和度 <= 空闲阈值（默认20%）          │
│ 条件3: 任务的key没有亲和性约束 或 亲和性允许借用       │
└─────────────────────────────────────────────────────────┘

2.2 借用的四种场景

场景1: 慢命令 → 借用快池

触发条件:

// 1. 这是一个慢命令
is_slow_cmd == true

// 2. 慢池繁忙（饱和度 >= 75%）
slow_queue_size >= slow_borrow_threshold

// 3. 快池空闲（饱和度 <= 20%）
fast_queue_size <= fast_idle_threshold

// 4. 该命令没有key，或者key的亲和性不在慢池
!has_key || !key_affinity_to_slow

执行流程:

慢命令进入
    ↓
检查慢池状态: 队列75/100 (75%)  ← 慢池繁忙
    ↓
检查快池状态: 队列10/100 (10%)  ← 快池空闲
    ↓
检查key亲和性: key不存在 或 key属于快池
    ↓
决策: 借用快池 ✓
    ↓
任务调度到快池执行
    ↓
更新指标: slow_pool_metrics->successful_borrows++

代码实现:

if (is_slow_cmd) {
    if (has_key && !key_affinity_to_slow) {
        // Key属于快池，必须去快池（不算借用，是亲和性路由）
        pika_client_processor_->SchedulePool(func, arg);
    } else if (slow_queue_size >= slow_borrow_threshold && 
               fast_queue_size <= fast_idle_threshold) {
        if (has_key && key_affinity_to_slow) {
            // Key属于慢池，不能借用，必须保证顺序性
            pika_slow_cmd_thread_pool_->Schedule(func, arg);
        } else {
            // 可以借用快池
            slow_pool_metrics_->borrow_attempts++;
            slow_pool_metrics_->successful_borrows++;
            pika_client_processor_->SchedulePool(func, arg);
            LOG(INFO) << "Slow cmd " << cmd_name << " borrows fast pool";
        }
    } else {
        // 常规路由到慢池
        pika_slow_cmd_thread_pool_->Schedule(func, arg);
    }
}

场景2: 快命令 → 借用慢池

触发条件:

// 1. 这是一个快命令
is_slow_cmd == false

// 2. 快池繁忙（饱和度 >= 75%）
fast_queue_size >= fast_borrow_threshold

// 3. 慢池空闲（饱和度 <= 20%）
slow_queue_size <= slow_idle_threshold

// 4. 该命令没有key，或者key的亲和性不在快池
!has_key || key_affinity_to_slow

执行流程:

快命令进入
    ↓
检查快池状态: 队列80/100 (80%)  ← 快池繁忙
    ↓
检查慢池状态: 队列15/100 (15%)  ← 慢池空闲
    ↓
检查key亲和性: key不存在 或 key属于慢池
    ↓
决策: 借用慢池 ✓
    ↓
任务调度到慢池执行
    ↓
更新指标: fast_pool_metrics->successful_borrows++

场景3: 有key且key属于对方池（强制路由）

这种情况不算借用，而是强制的亲和性路由：

示例1: 慢命令但key属于快池
命令: HGETALL large_hash_key_123
分类: 慢命令（因为是大key）
key亲和性: large_hash_key_123 → hash计算 → 快池

决策: 必须路由到快池（虽然是慢命令）
原因: 保证large_hash_key_123的所有操作顺序性

示例2: 快命令但key属于慢池
命令: GET key_456
分类: 快命令
key亲和性: key_456 → hash计算 → 慢池

决策: 必须路由到慢池（虽然是快命令）
原因: 保证key_456的所有操作顺序性

场景4: 无法借用（正常路由）

情况1: 两个池都繁忙或都空闲

快池: 80/100 (80%)  ← 繁忙
慢池: 70/100 (70%)  ← 繁忙
决策: 不借用，按命令类型正常路由

情况2: 有key亲和性约束

慢命令: KEYS pattern*
慢池饱和度: 80% (可借用)
快池饱和度: 10% (空闲)
但该命令没有key，属于全局扫描

决策: 仍然路由到慢池（保持设计一致性）

2.3 借用阈值的动态调整

系统每处理100个命令会自动调整借用阈值：

void AdjustBorrowThresholds() {
    // 计算两个池的饱和度
    double fast_saturation = fast_queue_size / fast_max_queue;
    double slow_saturation = slow_queue_size / slow_max_queue;
    
    int current_threshold = g_pika_conf->threadpool_borrow_threshold_percent();
    int new_threshold = current_threshold;
    
    // 规则1: 两个池都很忙(饱和度>80%) → 提高阈值(更难借用)
    if (fast_saturation > 0.8 && slow_saturation > 0.8) {
        new_threshold = min(90, current_threshold + 5);
        // 提高到90%才能借用，避免互相干扰
    }
    // 规则2: 两个池都很闲(饱和度<30%) → 降低阈值(更容易借用)
    else if (fast_saturation < 0.3 && slow_saturation < 0.3) {
        new_threshold = max(30, current_threshold - 5);
        // 降低到30%就可以借用，提高资源利用率
    }
    
    if (new_threshold != current_threshold) {
        g_pika_conf->SetThreadpoolBorrowThresholdPercent(new_threshold);
        LOG(INFO) << "Adjusted borrow threshold: " << current_threshold 
                  << "% → " << new_threshold << "%";
    }
}

调整逻辑图示:

系统负载状态                  借用阈值调整
┌────────────────────┐       ┌──────────────┐
│ 两池都很忙(>80%)   │  →    │ 90% (更严格) │
│ 避免互相抢资源     │       └──────────────┘
└────────────────────┘

┌────────────────────┐       ┌──────────────┐
│ 正常负载(30%-80%)  │  →    │ 75% (默认值) │
│ 保持当前策略       │       └──────────────┘
└────────────────────┘

┌────────────────────┐       ┌──────────────┐
│ 两池都很闲(<30%)   │  →    │ 30% (更宽松) │
│ 鼓励资源共享       │       └──────────────┘
└────────────────────┘

---

3. 键亲和性路由机制

3.1 一致性哈希实现

为什么使用一致性哈希而不是简单取模？

简单取模的问题:
hash(key) % 2 → 0(快池) 或 1(慢池)

问题: 如果调整线程池数量（比如快池从8线程扩展到16线程），
      需要重新分配所有key，破坏了已有的亲和性映射

一致性哈希的优势:
使用虚拟节点环，添加/删除节点只影响相邻节点的key分配

3.2 哈希环的构建

class ConsistentHash {
private:
    int num_replicas_ = 100;              // 每个物理节点100个虚拟节点
    map<size_t, string> ring_;            // 哈希环(有序map)
    
public:
    ConsistentHash() {
        // 初始化时添加两个物理节点: "fast" 和 "slow"
        AddNode("fast");
        AddNode("slow");
    }
    
    void AddNode(const string& node) {
        for (int i = 0; i < num_replicas_; i++) {
            // 为每个物理节点创建100个虚拟节点
            string virtual_node = node + ":" + to_string(i);
            size_t hash = hasher_(virtual_node);
            ring_[hash] = node;  // 虚拟节点指向物理节点
        }
        // 结果: fast有100个虚拟节点, slow有100个虚拟节点
        // 总共200个虚拟节点均匀分布在哈希环上
    }
};

哈希环结构示意图:

                    0 (哈希空间起点)
                    │
        fast:15 ←───┤───→ slow:23
                    │
                    │
    slow:87         │         fast:42
        ↖           │           ↗
           ╲        │        ╱
              ╲     │     ╱
                 ╲  │  ╱
    270° ←───────── ┼ ────────→ 90°
                 ╱  │  ╲
              ╱     │     ╲
           ╱        │        ╲
        ↙           │           ↘
    fast:198        │         slow:156
                    │
        slow:245 ←──┤──→ fast:267
                    │
                    ▼
              180° (哈希空间中点)

说明: 
- 圆环上均匀分布200个虚拟节点
- fast的虚拟节点和slow的虚拟节点交替出现
- 每个虚拟节点指向实际的物理节点（快池或慢池）

cat > docs/同一key保持在同一线程池原理.md << 'EOF'
# 同一个key为何始终在同一个线程池 - 详解

## 核心原理：哈希函数的确定性

一致性哈希算法能够保证同一个key在不同时刻计算得到相同的线程池归属，关键在于**哈希函数的确定性和哈希环的不变性**。

### 哈希函数确定性

哈希函数的一个基本特性是：**对于相同的输入，总是产生相同的输出**。

```cpp
// C++标准库的哈希函数示例
std::hash<std::string> hasher;

// 多次计算相同key的哈希值
size_t hash1 = hasher("user:123");  // 例如得到 8675309
size_t hash2 = hasher("user:123");  // 仍然是 8675309
size_t hash3 = hasher("user:123");  // 永远都是 8675309

这意味着无论何时计算"user:123"的哈希值，结果都是一样的。

哈希环的不变性

哈希环在系统启动时建立，之后保持不变：

// 系统启动时初始化一次
void InitHashRing() {
    // 为"fast"物理节点创建100个虚拟节点
    for (int i = 0; i < 100; i++) {
        AddVirtualNode("fast", i);
    }
    
    // 为"slow"物理节点创建100个虚拟节点
    for (int i = 0; i < 100; i++) {
        AddVirtualNode("slow", i);
    }
    
    // 初始化完成后，哈希环上的200个点位置固定不变
}

一旦哈希环建立好，每个虚拟节点的位置就固定下来了。

组合效应：为什么同一个key始终路由到同一个线程池

结合上述两个特性，每次路由key的过程是这样的：

1. key的哈希值永远相同
2. 哈希环上虚拟节点的分布永远相同
3. 查找算法(lower_bound)的行为确定且一致

因此：

同一个key → 相同的哈希值 → 在相同的哈希环上查找 → 找到相同的虚拟节点 → 返回相同的物理节点(线程池)

图解说明

假设我们的哈希环如下（简化版）：

      0
      |
9 ----+---- 1
|            |
|            |
8            2
|            |
|            |
7 ----+---- 3
      |
      6     5
       ___/
         4

虚拟节点分布：

• 0位置: fast:0
• 2位置: slow:0
• 4位置: slow:1
• 5位置: fast:1
• 7位置: slow:2
• 9位置: fast:2

当我们多次计算"user:123"的路由时：

第一次计算:

1. hash("user:123") = 3
2. 在环上找到第一个大于等于3的点 → 位置4的slow:1
3. 返回"slow"

第二次计算:

1. hash("user:123") 仍然等于 3（哈希函数确定性）
2. 环上的节点分布没有改变
3. 找到的仍然是位置4的slow:1
4. 返回"slow"

第N次计算:

1. hash("user:123") 永远等于 3
2. 环上节点分布不变
3. 返回结果永远是"slow"

代码验证

可以通过下面的代码验证同一key的路由结果始终一致：

void VerifyKeyConsistency() {
    ConsistentHash hash(100); // 每个物理节点100个虚拟节点
    hash.AddNode("fast");
    hash.AddNode("slow");
    
    std::string key = "user:123";
    
    // 连续计算1000次，检查结果是否一致
    std::string first_result = hash.GetNode(key);
    
    for (int i = 0; i < 1000; i++) {
        std::string result = hash.GetNode(key);
        if (result != first_result) {
            std::cout << "不一致! 迭代 " << i << ": " 
                      << result << " vs " << first_result << std::endl;
            return;
        }
    }
    
    std::cout << "验证通过: key '" << key 
              << "' 始终映射到 " << first_result << std::endl;
}

实际应用的例子

当系统处理关于"user:123"的命令时：

时间T1: 收到 SET user:123 100
1. hash("user:123") = 某个值X
2. 该值X对应哈希环上的"slow"池
3. 命令路由到"slow"池处理

---系统继续运行几个小时---

时间T2: 收到 GET user:123
1. hash("user:123") = 同样的值X
2. 该值X对应哈希环上的"slow"池
3. 命令仍然路由到"slow"池处理

---系统重启---

时间T3: 收到 INCR user:123
1. hash("user:123") = 同样的值X
2. 该值X对应哈希环上的"slow"池
3. 命令仍然路由到"slow"池处理

总结

同一个key在多次计算中始终路由到同一个线程池的原因是：

1. 确定性哈希函数: 相同输入 → 相同输出
2. 固定的哈希环: 系统启动后哈希环布局不变
3. 一致性的查找算法: lower_bound找到的总是同一个位置

这三个因素结合保证了：无论何时计算，相同的key总会被路由到相同的线程池，即使系统重启也不会改变这一结果。

这种设计使得系统不需要保存任何"key → 线程池"的映射关系，每次都可以"即时计算"，减少了存储开销和同步复杂性，同时保证了命令处理的顺序性。