varch/doc/cpul.md

## 介绍

`cpul` 是一个用于C语言的简单CPU负载（cpuload）模块，定义了一系列与CPU负载管理相关的数据结构、宏以及函数接口，旨在方便开发者在C语言项目中对CPU负载进行控制和监测等操作。

## 接口

### 函数

#### `cpul_init`函数
```c
int cpul_init(CPUL *cpul);
```
**功能描述**：用于初始化`CPUL`实例，将`CPUL`结构初始化为默认值，并检查传入指针的有效性。初始化需要提供获取原始的负载的函数方法，针对linux的cpuload可以参考 [test_cpul.c](/test/test_cpul.c)。 

#### `cpul_get`函数
```c
int cpul_get(CPUL *cpul, uint16_t *load);
```
**功能描述**：从`CPUL`实例中获取当前的CPU负载值，同时会检查参数以及状态的有效性。

#### `cpul_set`函数
```c
int cpul_set(CPUL *cpul, uint16_t load);
```
**功能描述**：设置`CPUL`实例的目标CPU负载值，会对传入的参数进行有效性检查。

#### `cpul_task`函数
```c
int cpul_task(CPUL *cpul);
```
**功能描述**：执行一个CPU负载管理任务，根据当前负载值和目标负载值来对CPU负载进行管理操作。

**使用例子**：
```c
void *loadgen_entry(void *ptr)
{
    #define PERIOD 10
    const int coreid = *(int *)ptr;
    CPUL cpul;
    int ret = 0;
    uint32_t count = 0;
    uint16_t load = 0;

    cpul.coreid = coreid;
    cpul.resolution = 10;
    cpul.raw = cpul_raw;
    ret = cpul_init(&cpul);

    ret = cpul_set(&cpul, 5000);

    while(1)
    {
        count += PERIOD;
        if (count >= 25200000) count = 0;

        if (count % 1000 == 0)
        {
            ret = cpul_get(&cpul, &load);
            printf("cpul_get<%d> %2d.%02d%%, %d, %d\r\n", coreid, (uint16_t)(load / 100), load % 100, cpul.ctrl.tload, cpul.ctrl.refine);
        }

        cpul_task(&cpul);
        usleep(1000 * PERIOD);
    }
}
```

通过这些函数接口，开发者可以方便地在C语言程序中实现对CPU负载的初始化、获取、设置以及管理等功能。