# PTOS

**Repository Path**: wwddgod/ptos

## Basic Information

- **Project Name**: PTOS
- **Description**: 一个硬件无关的，移植超简单的，非抢占式任务调度工具，有优先级，使用函数添加任务，无需设置堆栈，任务可随时关闭、打开、设置延时启动等。
- **Primary Language**: C
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-08-14
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PTOS 任务调度器项目

## 📁 项目结构

```
ptos/
├── functionhandle.h          # 调度器头文件（API定义）
├── functionhandle.c          # 调度器核心实现
├── devicehandle.h            # 设备句柄占位文件
├── test_scheduler.c          # Windows控制台测试程序
├── example_usage.c           # 使用示例代码
├── build_test.bat            # 编译脚本（自动检测编译器）
├── run_test.bat              # 快速运行脚本
├── TEST_README.md            # 测试指南文档
└── README.md                 # 本文件
```

## 🎯 项目简介

这是一个轻量级的**基于优先级的协作式任务调度器**，专为嵌入式系统设计，同时提供Windows测试环境。

### 核心特性

✅ **优先级调度** - 数值越大优先级越高  
✅ **周期性任务** - 自动按周期触发  
✅ **事件驱动** - 支持手动触发任务  
✅ **延迟执行** - 支持延时启动  
✅ **动态配置** - 运行时修改周期/优先级  
✅ **性能统计** - 实时监控任务执行频率  
✅ **阻塞等待** - 协作式等待（不阻塞其他任务）  
✅ **资源占用低** - 适合资源受限的嵌入式系统  

## 🚀 快速开始

### 1. 编译测试程序

```bash
# Windows下双击运行
build_test.bat

# 或在命令行中运行
.\build_test.bat
```

### 2. 运行测试

```bash
# 方式1：使用快速运行脚本
run_test.bat

# 方式2：直接运行可执行文件
build\test_scheduler.exe
```

### 3. 选择测试项

程序启动后，输入对应数字选择测试：
- **1** - 基础优先级调度测试
- **2** - 事件触发任务测试
- **3** - 延迟执行测试
- **4** - 动态周期修改测试
- **5** - 阻塞等待测试
- **A** - 运行所有测试（推荐首次使用）
- **Q** - 退出程序

## 📖 使用说明

### 在嵌入式系统中使用

```c
#include "functionhandle.h"

// 1. 定义任务函数
void my_task(void)
{
    // 你的任务代码
}

// 2. 初始化调度器
int main(void)
{
    newsfunh(&sfunchandle);
    
    // 3. 注册任务（优先级100，周期10ms）
    FUNCID task_id = sfunchandle.func_reg(
        &sfunchandle, 
        my_task, 
        100,    // 优先级
        10      // 周期(ms)
    );
    
    // 4. 启动1ms定时器中断
    Timer_Init(1ms);
    
    // 5. 主循环
    while(1)
    {
        sfunchandle.func_handle(&sfunchandle);
    }
}

// 6. 在1ms定时器中断中调用
void TIM_IRQHandler(void)
{
    sfunchandle.func_time_handle_1ms(&sfunchandle);
}
```

### API 参考

#### 初始化
```c
void newsfunh(SFUNH *thiss);
```

#### 任务注册
```c
FUNCID func_reg(SFUNH *thiss, fun_p func, uint32_t priority, uint32_t period);
```
- `func`: 任务函数指针
- `priority`: 优先级（数值越大优先级越高）
- `period`: 执行周期（毫秒），0表示不自动触发
- **返回值**: 任务ID

#### 任务控制
```c
// 立即触发任务
void func_setready(SFUNH *thiss, FUNCID funcid);

// 延迟执行（毫秒）
void func_setdelay(SFUNH *thiss, FUNCID funcid, uint32_t delay);

// 修改周期
void func_setperiod(SFUNH *thiss, FUNCID funcid, uint32_t period);

// 阻塞等待（协作式）
void func_waithere(SFUNH *thiss, FUNCID funcid, uint32_t timeout);
```

#### 调度器核心
```c
// 主调度函数（在主循环中调用）
void func_handle(SFUNH *thiss);

// 时间处理（在1ms中断中调用）
void func_time_handle_1ms(SFUNH *thiss);
```

## 🔧 技术细节

### 调度算法

采用**固定优先级抢占式调度**（实际上是协作式）：

1. 每次调度时遍历所有任务
2. 找出所有就绪任务中优先级最高的
3. 执行该任务
4. 清除就绪标志，重置周期计数器

### 时间管理

- 使用1ms定时器中断作为时间基准
- 每个任务维护两个计数器：
  - `ifunc_period[]` - 周期计数器
  - `ifunc_delay[]` - 延迟计数器
- 计数器减到1时设置任务为就绪状态

### 任务状态机

```
未就绪 (isready=0)
    ↓
周期/延迟计数器递减（每1ms）
    ↓
计数器归零
    ↓
就绪 (isready=1)
    ↓
被调度器选中执行
    ↓
执行完成，清除就绪标志
    ↓
返回未就绪状态
```

## 📊 性能指标

### 资源占用

| 项目 | 数值 |
|------|------|
| 最大任务数 | 20 (TASKCNTMAX) |
| 内存占用 | ~1KB (取决于任务数) |
| CPU开销 | 极低（仅调度时） |
| 调度延迟 | O(n)，n为任务数 |

### 时间精度

- **理论精度**: 1ms
- **实际精度**: 取决于硬件定时器
- **抖动**: < 1ms（嵌入式系统）

## ⚠️ 注意事项

### 设计限制

1. **最多20个任务** - 可通过修改`TASKCNTMAX`调整
2. **非抢占式** - 任务必须主动让出CPU
3. **单核设计** - 不支持多核并行
4. **无优先级继承** - 可能存在优先级反转问题

### 最佳实践

✅ **任务应该短小精悍**
- 避免长时间运行
- 复杂任务拆分为多个小任务

✅ **合理设置优先级**
- 高优先级：实时性要求高的任务
- 低优先级：后台处理任务
- idle任务：最低优先级（已自动注册）

✅ **避免在任务中阻塞**
- 不要使用忙等待循环
- 需要等待时使用`func_waithere()`

❌ **不要在任务中禁用中断**
- 会影响定时器计数
- 导致调度不准确

## 🧪 测试说明

详细测试指南请参考：[TEST_README.md](TEST_README.md)

### 测试覆盖

- ✅ 优先级调度正确性
- ✅ 周期性任务执行
- ✅ 事件触发机制
- ✅ 延迟执行功能
- ✅ 动态参数修改
- ✅ 阻塞等待行为
- ✅ 性能统计准确性

### 已知限制（Windows测试环境）

⚠️ Windows不是实时操作系统：
- 定时器精度有限（1-15ms）
- 线程调度有抖动
- 不适合测试硬实时特性
- 结果仅供参考，以实际嵌入式环境为准

## 🛠️ 开发工具

### 必需工具

- **C编译器**: GCC (MinGW) 或 MSVC
- **Windows系统**: Windows 7及以上

### 可选工具

- **GDB**: 调试
- **Valgrind**: 内存检查（Linux）
- **Perf**: 性能分析

## 📝 版本历史

### v1.1 (当前版本)
- ✅ 修复调度算法bug
- ✅ 添加边界检查
- ✅ 完善注释和文档
- ✅ 创建Windows测试环境
- ✅ 提供完整使用示例

### v1.0 (初始版本)
- 基础优先级调度
- 周期性任务支持
- 简单的事件触发

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

### 改进方向

- [ ] 支持任务删除
- [ ] 添加优先级继承机制
- [ ] 支持任务间通信（消息队列）
- [ ] 添加看门狗功能
- [ ] 支持多实例调度器
- [ ] 提供更精确的性能统计

## 📄 许可证

本项目采用 MIT 许可证

## 📧 联系方式

如有问题或建议，请提交Issue。

---

**祝使用愉快！** 🎉