Wait

Wait 提供 OSAL（Operating System Abstraction Layer）的等待队列机制，支持线程在指定条件满足前阻塞睡眠、超时自动唤醒以及主动唤醒等待队列上的线程，用于线程间同步与事件等待。

模块公共头文件

#include "kernel/osal/include/schedule/osal_wait.h"

接口清单

接口名称	功能简述
osal_wait_init	初始化一个等待队列
osal_wait_interruptible	阻塞睡眠直到条件为真或被信号打断
osal_wait_uninterruptible	阻塞睡眠（不可中断）直到条件为真
osal_wait_timeout_interruptible	阻塞睡眠直到条件为真、超时或被信号打断
osal_wait_timeout_uninterruptible	阻塞睡眠（不可中断）直到条件为真或超时
osal_wait_wakeup	唤醒阻塞在等待队列上的线程
osal_wait_wakeup_interruptible	唤醒阻塞在等待队列上的可中断等待线程
osal_wait_destroy	销毁等待队列并释放其占用的资源

Functions

osal_wait_init

int osal_wait_init(osal_wait *wait)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

初始化一个等待队列，使其进入可用状态。
成功初始化后该等待队列可用于阻塞等待、唤醒与销毁操作。
支持 linux、LiteOS、FreeRTOS 系统。

前置条件

调用时序约束：wait 指向的 osal_wait 结构体须由调用方预先分配，且 wait->wait 必须为 NULL（未重复初始化）。
上下文限制：成功初始化后方可调用等待、唤醒与销毁接口。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	待初始化的等待队列句柄	不为 NULL 且 wait->wait 为 NULL

返回值

返回类型：int

返回值	文字含义	触发场景
0	执行成功（OSAL_SUCCESS）	等待队列初始化成功
-1	执行失败（OSAL_FAILURE）	wait 为 NULL、wait->wait 非空（已初始化）或底层资源分配失败

参考案例

src/middleware/utils/hcc/comm/hcc.c

osal_wait_interruptible

int osal_wait_interruptible(osal_wait *wait, osal_wait_condition_func func, const void *param)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

阻塞当前线程睡眠，直到条件函数返回真或收到信号。
每次等待队列被唤醒时检查条件函数的返回值。
在 LiteOS 上等价于 osal_wait_uninterruptible（不支持可中断等待）。
支持 linux、LiteOS 系统。

前置条件

调用时序约束：当前接口必须在 osal_wait_init 成功返回后调用。
上下文限制：当前接口会阻塞当前线程，禁止在中断上下文调用。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	等待的等待队列句柄	不为 NULL 且 wait->wait 已初始化
func	osal_wait_condition_func	条件判断回调函数，每次唤醒时调用；为 NULL 时按永真条件等待	为 NULL 或指向有效的条件判断函数
param	const void *	传递给条件判断回调函数的参数	-

返回值

返回类型：int

返回值	文字含义	触发场景
0	执行成功（OSAL_SUCCESS）	条件满足或被唤醒
-1	执行失败（OSAL_FAILURE）	wait 为 NULL 或 wait->wait 为 NULL
-512	被信号中断（-OSAL_ERESTARTSYS）	Linux 下被信号打断；LiteOS 不产生该返回值

参考案例

src/middleware/utils/hcc/comm/hcc.c

osal_wait_uninterruptible

int osal_wait_uninterruptible(osal_wait *wait, osal_wait_condition_func func, const void *param)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

阻塞当前线程睡眠（不可中断），直到条件函数返回真。
每次等待队列被唤醒时检查条件函数的返回值。
支持 linux、LiteOS、FreeRTOS 系统。

前置条件

调用时序约束：当前接口必须在 osal_wait_init 成功返回后调用。
上下文限制：当前接口会阻塞当前线程，禁止在中断上下文调用。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	等待的等待队列句柄	不为 NULL 且 wait->wait 已初始化
func	osal_wait_condition_func	条件判断回调函数，每次唤醒时调用；为 NULL 时按永真条件等待	为 NULL 或指向有效的条件判断函数
param	const void *	传递给条件判断回调函数的参数	-

返回值

返回类型：int

返回值	文字含义	触发场景
0	执行成功（OSAL_SUCCESS）	条件满足或被唤醒
-1	执行失败（OSAL_FAILURE）	wait 为 NULL 或 wait->wait 为 NULL

osal_wait_timeout_interruptible

int osal_wait_timeout_interruptible(osal_wait *wait, osal_wait_condition_func func, const void *param, unsigned long ms)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

阻塞当前线程睡眠，直到条件函数返回真、超时或收到信号。
超时时间以毫秒为单位。
支持 linux、LiteOS、FreeRTOS 系统。

前置条件

调用时序约束：当前接口必须在 osal_wait_init 成功返回后调用。
上下文限制：当前接口会阻塞当前线程，禁止在中断上下文调用。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	等待的等待队列句柄	不为 NULL 且 wait->wait 已初始化
func	osal_wait_condition_func	条件判断回调函数，每次唤醒时调用；为 NULL 时按永真条件等待并默认返回超时	为 NULL 或指向有效的条件判断函数
param	const void *	传递给条件判断回调函数的参数	-
ms	unsigned long	超时时间，单位 ms	0 ~ 0xFFFFFFFF；OSAL_WAIT_FOREVER：0xFFFFFFFF 表示永久等待

返回值

返回类型：int

返回值	文字含义	触发场景
0	超时且条件未满足	超时结束后条件仍为假
大于 0	条件已满足，返回剩余时间	条件在超时前满足，返回剩余 tick 数（Linux 为 jiffies）；LiteOS 下条件在超时点为真时返回 1
-1	参数无效（OSAL_FAILURE）	wait 为 NULL 或 wait->wait 为 NULL
-512	被信号中断（-OSAL_ERESTARTSYS）	Linux 下被信号打断

参考案例

src/middleware/utils/hcc/comm/hcc_flow_ctrl.c

osal_wait_timeout_uninterruptible

int osal_wait_timeout_uninterruptible(osal_wait *wait, osal_wait_condition_func func, const void *param, unsigned long ms)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

阻塞当前线程睡眠（不可中断），直到条件函数返回真或超时。
超时时间以毫秒为单位。
支持 linux、LiteOS 系统。

前置条件

调用时序约束：当前接口必须在 osal_wait_init 成功返回后调用。
上下文限制：当前接口会阻塞当前线程，禁止在中断上下文调用。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	等待的等待队列句柄	不为 NULL 且 wait->wait 已初始化
func	osal_wait_condition_func	条件判断回调函数，每次唤醒时调用；为 NULL 时按永真条件等待	为 NULL 或指向有效的条件判断函数
param	const void *	传递给条件判断回调函数的参数	-
ms	unsigned long	超时时间，单位 ms	0 ~ 0xFFFFFFFF；OSAL_WAIT_FOREVER：0xFFFFFFFF 表示永久等待

返回值

返回类型：int

返回值	文字含义	触发场景
0	超时且条件未满足	超时结束后条件仍为假
大于 0	条件已满足，返回剩余时间	条件在超时前满足，返回剩余 tick 数（Linux 为 jiffies）
-1	参数无效（OSAL_FAILURE）	wait 为 NULL 或 wait->wait 为 NULL

osal_wait_wakeup

void osal_wait_wakeup(osal_wait *wait)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

唤醒阻塞在指定等待队列上的所有线程。
与等待接口（如 osal_wait_uninterruptible）配对使用。
支持 linux、LiteOS、FreeRTOS 系统。

前置条件

调用时序约束：当前接口必须在 osal_wait_init 成功返回后调用。
依赖关系：改变等待条件后须调用本接口唤醒等待队列上的线程。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	待唤醒的等待队列句柄	不为 NULL 且 wait->wait 已初始化

参考案例

src/middleware/utils/hcc/comm/hcc.c

osal_wait_wakeup_interruptible

void osal_wait_wakeup_interruptible(osal_wait *wait)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

唤醒阻塞在指定等待队列上的可中断等待线程。
与 osal_wait_interruptible 配对使用。
在 LiteOS 上等价于 osal_wait_wakeup。
支持 linux、LiteOS 系统。

前置条件

调用时序约束：当前接口必须在 osal_wait_init 成功返回后调用。
依赖关系：改变等待条件后须调用本接口唤醒等待队列上的线程。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	待唤醒的等待队列句柄	不为 NULL 且 wait->wait 已初始化

osal_wait_destroy

void osal_wait_destroy(osal_wait *wait)

声明头文件

#include "kernel/osal/include/schedule/osal_wait.h"

功能说明

销毁等待队列并释放其占用的资源。
销毁后 wait->wait 被置空，等待队列不可再使用。
支持 linux、LiteOS、FreeRTOS 系统。

前置条件

调用时序约束：当前接口必须在 osal_wait_init 成功返回后调用。
依赖关系：销毁后等待队列不可再使用，调用方应确保无其他线程正在该队列上等待。

入参

名称	参数类型	说明	约束取值范围
wait	osal_wait *	待销毁的等待队列句柄	不为 NULL 且 wait->wait 已初始化

参考案例

src/middleware/utils/hcc/comm/hcc.c

Type definitions

osal_wait_condition_func

/* return value is a bool type */
typedef int (*osal_wait_condition_func)(const void *param);

使用说明

等待队列条件判断回调函数指针类型，在 osal_wait_interruptible、osal_wait_uninterruptible、osal_wait_timeout_interruptible、osal_wait_timeout_uninterruptible 等待接口中每次唤醒时被调用以判定等待条件是否满足。

回调说明：

调用时机：等待队列每次被唤醒时调用。
参数 param：由等待接口的 param 入参透传而来，用于条件判定的上下文数据。
返回值处理：返回非零值表示条件满足（结束等待），返回 0 表示条件未满足（继续等待）；返回值按布尔类型使用。

Structures

osal_wait

typedef struct {
    void *wait;
} osal_wait;

成员说明

成员名称	数据类型	描述
wait	void *	等待队列底层句柄；由 osal_wait_init 写入，调用方不应直接访问或修改

Macros

OSAL_WAIT_FOREVER

#define OSAL_WAIT_FOREVER 0xFFFFFFFF