# adaptive-lock

**Repository Path**: stkid/adaptive-lock

## Basic Information

- **Project Name**: adaptive-lock
- **Description**: adaptive-lock implemented by OpenClaw
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Adaptive Lock - 自适应内核锁

## 简介

这是一个 Linux 内核模块，实现了一个**自适应锁**（Adaptive Lock），能够根据运行时特征动态调整同步策略，以获得最优的吞吐量性能。

## 特性

### 🎯 自适应策略

锁会根据以下运行时特征自动调整：

1. **读写比例** - 自动检测读操作和写操作的比例
2. **竞争压力** - 统计读写竞争次数
3. **临界区大小** - 测量持锁时间

### 🔄 支持的锁模式

| 模式 | 适用场景 | 特点 |
|------|---------|------|
| **seqlock** | 读多写少，低竞争 | 读者完全无锁，写者更新版本号 |
| **rwlock (spin)** | 短临界区，中等竞争 | 自旋读写锁，避免上下文切换 |
| **rw_semaphore** | 长临界区，高竞争 | 睡眠读写锁，避免 CPU 空转 |
| **mutex** | 写多读少，长临界区 | 互斥锁，保证独占访问 |

## 编译和安装

### 编译模块

```bash
cd /home/li/.openclaw/workspace/kernel-modules/adaptive-lock
make
```

### 加载模块

```bash
sudo insmod adaptive_lock.ko
```

### 卸载模块

```bash
sudo rmmod adaptive_lock
```

### 查看日志

```bash
dmesg | grep adaptive_lock
```

## 使用方法

### 在内核代码中使用

```c
#include "adaptive_lock.h"

// 初始化锁
struct adaptive_lock *lock = adaptive_lock_init();

// 读操作
adaptive_read_lock(lock);
// ... 读取受保护的数据 ...
adaptive_read_unlock(lock);

// 写操作
adaptive_write_lock(lock);
// ... 修改受保护的数据 ...
adaptive_write_unlock(lock);

// 销毁锁
adaptive_lock_destroy(lock);
```

## 模块参数

加载模块时可以调整以下参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `contention_threshold` | 100 | 竞争阈值，超过此值认为竞争激烈 |
| `hold_time_threshold` | 10000 | 持锁时间阈值（ns），超过此值使用睡眠锁 |
| `adjust_interval` | 1000 | 策略调整间隔（操作次数） |
| `hysteresis` | 10 | 滞后百分比，防止策略频繁切换 |

### 示例

```bash
# 加载模块并设置参数
sudo insmod adaptive_lock.ko \
    contention_threshold=200 \
    hold_time_threshold=5000 \
    adjust_interval=500 \
    hysteresis=15
```

## 监控和调试

### 通过 sysfs 查看状态

```bash
# 查看当前锁模式
cat /sys/kernel/adaptive_lock/mode

# 查看统计信息
cat /sys/kernel/adaptive_lock/stats
```

### 统计信息说明

- `read_ops` - 读操作总数
- `write_ops` - 写操作总数
- `read_ratio` - 读操作百分比
- `contentions` - 竞争次数
- `avg_hold_time_ns` - 平均持锁时间（纳秒）
- `read_retries` - seqlock 读取重试次数
- `spin_failures` - 自旋失败次数

## 性能优化建议

### 1. 调整阈值

根据实际场景调整模块参数：

```bash
# 高竞争场景
sudo insmod adaptive_lock.ko contention_threshold=500

# 长临界区场景
sudo insmod adaptive_lock.ko hold_time_threshold=50000

# 频繁调整策略
sudo insmod adaptive_lock.ko adjust_interval=100
```

### 2. 监控模式切换

```bash
# 实时监控锁模式
watch -n 1 'cat /sys/kernel/adaptive_lock/mode'

# 监控统计信息
watch -n 1 'cat /sys/kernel/adaptive_lock/stats'
```

## 决策矩阵

锁会根据以下规则自动选择最优策略：

| 读写比例 | 竞争 | 持锁时间 | 选择策略 |
|---------|------|---------|---------|
| >90% | 低 | 任意 | seqlock |
| >90% | 高 | <1us | rwlock (spin) |
| >90% | 高 | >1us | rw_semaphore |
| <10% | 任意 | <10us | rwlock (spin) |
| <10% | 任意 | >10us | mutex |
| ~50% | 低 | <1us | seqlock |
| ~50% | 高 | 任意 | rw_semaphore |

## 技术细节

### 持锁时间测量

锁使用 `ktime_get_ns()` 精确测量持锁时间，通过 per-CPU 变量记录获取锁的时间戳。

### 策略调整

策略调整不是每次锁操作都执行，而是根据 `adjust_interval` 参数周期性执行，避免过度开销。

### 滞后机制

使用 `hysteresis` 参数防止策略频繁切换，只有当指标显著变化时才切换策略。

## 限制和注意事项

1. **seqlock 限制** - 写操作期间不能睡眠
2. **内存开销** - 每个 CPU 需要额外的存储空间
3. **初始化开销** - 需要分配 per-CPU 内存
4. **调试** - 启用 CONFIG_DEBUG_LOCK_ALLOC 可帮助调试

## 未来改进

- [ ] 支持 RCU 模式
- [ ] 添加更细粒度的统计
- [ ] 支持 NUMA 感知
- [ ] 添加性能测试工具
- [ ] 支持 lockdep 调试

## 许可证

GPL-2.0

## 作者

Adaptive Lock Implementation

## 版本

1.0.0