# SwTask

**Repository Path**: zyanishere/sw-task

## Basic Information

- **Project Name**: SwTask
- **Description**: 受ProtoThread和nodejs promise的启发，封装了switch的相关操作，简化了状态机，实现了一些非阻塞式操作
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2022-12-21
- **Last Updated**: 2023-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SwTask

#### 介绍
受ProtoThread和nodejs promise的启发，封装了switch的相关操作，简化了状态机，实现了一些非阻塞式操作

## 软件架构
基于switch状态机实现异步，非阻塞操作。

*SW_BEGIN(s)* 封装了switch头和状态变量s。*SW_END(s)* 封装了switch尾，并重置状态变量s。

SW_SET(s)	实际上使用case标记了当前行，并讲当前行赋值给状态变量s，使得下次执行函数时，直接从begin跳到该行。

更高层的API的就是运用了switch状态机的特性，实现了异步任务等待，延时等功能。



- 分立任务情形
  - 任务通过 ***SW_DEALY*** 主动让出执行权，或者通过 ***SW_WAIT_UNTIL*** 被动让出
- 协程情形
  - 主任务通过 ***SW_WAIT_TASK*** 判断子任务是否完成
    - 子任务返回 *SW_WAITING*，未执行完成，或自己也在等待子任务执行完成。
    - 子任务返回 *SW_ENDED* ，主任务继续向下执行。
  - 如果需要异常处理（包含在SwTask_err.h），主任务可以通过 ***SW_WAIT_TASK_WITH_RESULT***  判断子任务是否出错
    - 子任务出错，返回 *SW_ERROR*
      - 主任务自己处理错误，继续向下执行
      - 主任务直接调用 ***SW_ERROR_CHECK*** ，间接调用*SW_RAISE_ERROR*，直接自身返回 *SW_ERROR*，将错误交给上一层主任务处理。
  - 在协程情况下，主任务和子任务可以不断嵌套。

## 安装教程

1. 直接将 SwTask.h 加入到代码中

2. 测试

   ```shell
   cd examples
   
   mkdir build
   cd build
   
   #linux下
   cmake ..
   make
   
   #windows下
   cmake ..
   cmake --build .
   ```



## 使用方法

- 创建任务状态全局变量或静态变量 ，并初始化为 0
- 函数返回值设置为 **char**
- 在函数头部嵌入 **SW_BEGIN(s)** ，在函数尾部嵌入 **SW_END(s)**
- 使用 **SW_WAIT_UNTIL** 、**SW_DELAY **或者 **SW_WAIT_TASK** 拆分任务，实现异步
  - 若子任务未完成（返回 *SW_WAITING*）, 主任务也直接返回 *SW_WAITING*
  - 若子任务完成（返回 *SW_ENDED*）, 主任务继续向下执行
- 示例见examples

## 使用文档

- ### 类型/常值定义
  - **SW_WAITING ：0**
    - 任务正在运行
  - **SW_ENDED：3**
    - 任务完成
  - **SW_ERROR  ：-1**
    - 任务出错
  - **sw_task_t**
    - uint16_t
    - sw任务类型，实际为uint16_t，存储当前任务的状态，即case值，而case值为当前行的行数。
  - **sw_tim_t**
    - uint16_t
    - 定时器装载值，用于SW_DEALY



- ### 基础
  
  - **SW_BEGIN(s)**
    - *s：sw_task_t*
    - 总入口，封装了switch头
  
  - **SW_END(s)**
    - *s：sw_task_t*
    - 总出口，封装了switch尾
  
  - **SW_SET(s)**
    - *s：sw_task_t*
    - 设置断点，封装了case
  


- ### 事件/ 任务


  - **SW_WAIT_UNTIL(s, condition)**


    - *s：sw_task_t*
    - *condition：表达式*
    - 异步等待
    
      - 先设定断点，即添加case并设置switch的值，使得函数再次运行时从该断点开始。
      - 再判断条件是否满足，不满足直接从switch中返回SW_WAITING，满足向下执行。

  - **SW_WAIT_TASK(s, task)**


    - *s：sw_task_t*
    - *task： 函数*
    - 异步等待
    
      - 创建断点，根据子任务的状态，决定返回或向下执行。
      - 子任务返回SW_WAITING则父任务继续等待，也直接返回SW_WAITING。子任务返回SW_ENDED则父任务向下执行。

  - **SW_DELAY(s, t, l)**

    - *s：sw_task_t*

    - *t：sw_tim_t*

    - *l：uint16_t，装载值*

    - 异步延时
      - 先装载定时器的值，再设定断点，然后不断减1，判断是否为0，不满足返回，满足向下执行

- ### 错误处理


  - **SW_WAIT_TASK_WITH_RESULT(s, task, result)**

    - *s：sw_task_t*
    - *task：函数*
    - *result：char*
    - 在异步等待任务的同时，接收返回值，用于异常处理
  - **SW_RAISE_ERROR(s)**
    - *s：sw_task_t*
    - 从异常中返回SW_ERROR，抛出异常
  - **SW_ERROR_CHECK(s, result)**

    - *s：sw_task_t*
    - *result：char*
    - 检测是否异常，并直接返回