completion

completion 提供内核完成量（completion）机制，用于线程间的同步等待与唤醒操作。

头文件清单

#include "include/osal/schedule/osal_completion.h"

接口清单

接口名称	功能简述
osal_completion_init	初始化动态分配的completion结构
osal_completion_reinit	重置completion计数为0
osal_complete	唤醒等待该completion的单个线程
osal_wait_for_completion	等待completion信号，不可中断且无超时
osal_wait_for_completion_timeout	等待completion信号，支持超时
osal_complete_all	唤醒等待该completion的所有线程
osal_complete_destory	释放动态分配的completion资源

Functions

osal_completion_init

int osal_completion_init(osal_completion *com)

头文件清单

#include "include/osal/schedule/osal_completion.h"

功能说明

初始化动态分配的completion结构体，内部完成内存分配与底层completion对象初始化
调用后completion结构体处于可用状态，可供后续等待/唤醒操作使用
初始化后的completion必须通过osal_complete_destory释放，禁止重复初始化同一completion

前置条件

入参com不为NULL，且com->completion为NULL（未初始化状态）
调用前未对该completion执行过初始化

入参

名称	参数类型	详细说明	约束取值范围
com	osal_completion *	指向待初始化的completion结构体指针	非NULL，且com->completion为NULL

出参

名称	数据类型	输出说明
com	osal_completion *	待初始化的completion结构体指针，由调用方分配内存、函数填充内部completion对象

返回值

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	初始化成功	completion内存分配与初始化完成
OSAL_FAILURE(-1)	初始化失败	com为NULL、com->completion非NULL或内存分配失败

osal_completion_reinit

void osal_completion_reinit(osal_completion *com)

头文件清单

#include "include/osal/schedule/osal_completion.h"

功能说明

重置completion的完成计数为0，使已处于完成状态的completion可被重新等待
适用于需要重复使用同一completion对象的场景
仅支持Linux系统

前置条件

入参com不为NULL
completion已通过osal_completion_init初始化完成

入参

名称	参数类型	详细说明	约束取值范围
com	osal_completion *	指向待重置的completion结构体指针	非NULL

osal_complete

void osal_complete(osal_completion *com)

头文件清单

#include "include/osal/schedule/osal_completion.h"

功能说明

唤醒等待该completion的单个线程，按排队顺序依次唤醒
执行全内存屏障后访问任务状态，确保唤醒操作可见性
若无线程等待，completion计数递增，后续等待线程将直接返回

前置条件

入参com不为NULL，且com->completion不为NULL
completion已通过osal_completion_init初始化完成

入参

名称	参数类型	详细说明	约束取值范围
com	osal_completion *	指向completion结构体指针	非NULL，且com->completion非NULL

osal_wait_for_completion

void osal_wait_for_completion(osal_completion *com)

头文件清单

#include "include/osal/schedule/osal_completion.h"

功能说明

阻塞等待completion信号，不可中断且无超时限制
若completion已完成则立即返回，否则阻塞当前线程直到被唤醒
调用线程将进入等待队列，由osal_complete或osal_complete_all唤醒

前置条件

入参com不为NULL，且com->completion不为NULL
调用时序约束：completion已通过osal_completion_init初始化完成
调用上下文约束：禁止在中断上下文中调用，可能导致系统死锁

入参

名称	参数类型	详细说明	约束取值范围
com	osal_completion *	指向等待的completion结构体指针	非NULL，且com->completion非NULL

osal_wait_for_completion_timeout

unsigned long osal_wait_for_completion_timeout(osal_completion *com, unsigned long timeout)

头文件清单

#include "include/osal/schedule/osal_completion.h"

功能说明

阻塞等待completion信号，支持超时，不可中断
在指定超时时间内等待completion完成，超时则返回0
若在超时前完成，返回剩余超时时间（正值），可用于判断剩余等待时间
超时单位在Linux下为jiffies，在LiteOS下为tick

前置条件

入参com不为NULL，且com->completion不为NULL
completion已通过osal_completion_init初始化完成
timeout值大于0

入参

名称	参数类型	详细说明	约束取值范围
com	osal_completion *	指向等待的completion结构体指针	非NULL，且com->completion非NULL
timeout	unsigned long	超时时间，Linux下为jiffies，LiteOS下为tick	大于0

返回值

返回值	文字含义	触发场景
0	超时	等待超时，completion未完成
正值	剩余超时时间	在超时前completion完成
OSAL_FAILURE(-1)	等待失败	com为NULL或com->completion为NULL

osal_complete_all

void osal_complete_all(osal_completion *com)

头文件清单

#include "include/osal/schedule/osal_completion.h"

功能说明

唤醒等待该completion的所有线程
执行全内存屏障后访问任务状态，确保唤醒操作可见性
唤醒后completion保持完成状态，后续所有等待线程均直接返回

前置条件

入参com不为NULL，且com->completion不为NULL
completion已通过osal_completion_init初始化完成

入参

名称	参数类型	详细说明	约束取值范围
com	osal_completion *	指向completion结构体指针	非NULL，且com->completion非NULL

osal_complete_destory

void osal_complete_destory(osal_completion *com)

头文件清单

#include "include/osal/schedule/osal_completion.h"

功能说明

释放动态分配的completion资源，释放内部completion对象占用的内存
释放后将com->completion置为NULL，防止悬垂指针
com必须由osal_completion_init初始化获得，禁止对未初始化的completion调用此接口

前置条件

入参com不为NULL，且com->completion不为NULL
completion已通过osal_completion_init初始化完成

入参

名称	参数类型	详细说明	约束取值范围
com	osal_completion *	指向待释放的completion结构体指针	非NULL，且com->completion非NULL

Structures

osal_completion

typedef struct {
    void *completion;
} osal_completion;

成员说明

成员名称	数据类型	描述
completion	void *	指向底层completion对象的指针，由osal_completion_init动态分配

Macros

OSAL_SUCCESS

#define OSAL_SUCCESS 0

OSAL_FAILURE

#define OSAL_FAILURE (-1)