跳转至
芯片
版本

completion

头文件清单 kernel/osal/include/schedule/osal_completion.h

接口清单

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

Functions

osal_completion_init 

int osal_completion_init(osal_completion *com)

头文件清单 kernel/osal/include/schedule/osal_completion.h

功能说明

  • 初始化动态分配的完成量结构体
  • 内部动态分配内存并初始化完成量状态
  • 必须通过 osal_complete_destory 释放资源

前置条件

  • com 指针不为 NULL，且 com->completion 为 NULL（未被初始化）
  • 系统内存资源充足，可完成动态内存分配

入参

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

返回值

  • 返回类型：int
返回值 文字含义 触发场景
OSAL_SUCCESS(0) 初始化成功 动态内存分配成功且完成量初始化完成
OSAL_FAILURE(-1) 初始化失败 com 为 NULL、com->completion 非 NULL 或动态内存分配失败

osal_complete 

void osal_complete(osal_completion *com)

头文件清单 kernel/osal/include/schedule/osal_completion.h

功能说明

  • 向完成量发送信号，唤醒单个等待该完成量的线程
  • 线程按排队顺序依次唤醒
  • 唤醒任务前执行全内存屏障

前置条件

  • com 指针不为 NULL，且 com->completion 不为 NULL（已完成初始化）

入参

名称 参数类型 详细说明 约束取值范围
com osal_completion * 已初始化的完成量结构体指针 非NULL，且completion字段非NULL

osal_wait_for_completion 

void osal_wait_for_completion(osal_completion *com)

头文件清单 kernel/osal/include/schedule/osal_completion.h

功能说明

  • 等待完成量信号，阻塞当前线程直到收到信号
  • 不可中断，无超时机制
  • 调用线程将阻塞直至其他线程调用 osal_complete 或 osal_complete_all

前置条件

  • com 指针不为 NULL，且 com->completion 不为 NULL（已完成初始化）
  • 不可在中断上下文中调用

入参

名称 参数类型 详细说明 约束取值范围
com osal_completion * 已初始化的完成量结构体指针 非NULL，且completion字段非NULL

osal_wait_for_completion_timeout 

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

头文件清单 kernel/osal/include/schedule/osal_completion.h

功能说明

  • 等待完成量信号，支持超时机制
  • 在 Linux 系统下 timeout 单位为 jiffies，在 LiteOS 系统下 timeout 单位为 tick
  • 不可中断
  • 超时到期仍未收到信号则返回 0

前置条件

  • com 指针不为 NULL，且 com->completion 不为 NULL（已完成初始化）
  • 不可在中断上下文中调用

入参

名称 参数类型 详细说明 约束取值范围
com osal_completion * 已初始化的完成量结构体指针 非NULL，且completion字段非NULL
timeout unsigned long 超时时间，Linux 下为 jiffies，LiteOS 下为 tick > 0

返回值

  • 返回类型：unsigned long
返回值 文字含义 触发场景
0 超时 等待超时到期仍未收到完成量信号
正值 剩余超时时间 在超时到期前收到完成量信号
-1 执行失败 com 为 NULL 或 com->completion 为 NULL

osal_complete_all 

void osal_complete_all(osal_completion *com)

头文件清单 kernel/osal/include/schedule/osal_completion.h

功能说明

  • 向完成量发送信号，唤醒所有等待该完成量的线程
  • 唤醒任务前执行全内存屏障
  • 适用于广播通知场景

前置条件

  • com 指针不为 NULL，且 com->completion 不为 NULL（已完成初始化）

入参

名称 参数类型 详细说明 约束取值范围
com osal_completion * 已初始化的完成量结构体指针 非NULL，且completion字段非NULL

osal_complete_destory 

void osal_complete_destory(osal_completion *com)

头文件清单 kernel/osal/include/schedule/osal_completion.h

功能说明

  • 释放动态分配的完成量资源，释放内部内存并将 completion 字段置 NULL
  • com 必须由 osal_completion_init 初始化获得

前置条件

  • com 指针不为 NULL，且 com->completion 不为 NULL（已完成初始化）
  • com 必须由 osal_completion_init 初始化，禁止释放未初始化的完成量

入参

名称 参数类型 详细说明 约束取值范围
com osal_completion * 已初始化的完成量结构体指针 非NULL，且completion字段非NULL

Structures

osal_completion 

typedef struct {
    void *completion;
} osal_completion;

成员说明：

成员名称 数据类型 描述
completion void * 完成量内部实现指针，由 osal_completion_init 动态分配