Wait#
Wait 提供 OSAL(Operating System Abstraction Layer)的等待队列机制,支持线程在指定条件满足前阻塞睡眠、超时自动唤醒以及主动唤醒等待队列上的线程,用于线程间同步与事件等待。
模块公共头文件
#include "kernel/osal/include/schedule/osal_wait.h"
接口清单#
接口名称 |
功能简述 |
|---|---|
初始化一个等待队列 |
|
阻塞睡眠直到条件为真或被信号打断 |
|
阻塞睡眠(不可中断)直到条件为真 |
|
阻塞睡眠直到条件为真、超时或被信号打断 |
|
阻塞睡眠(不可中断)直到条件为真或超时 |
|
唤醒阻塞在等待队列上的线程 |
|
唤醒阻塞在等待队列上的可中断等待线程 |
|
销毁等待队列并释放其占用的资源 |
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 |
待初始化的等待队列句柄 |
不为 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 |
等待的等待队列句柄 |
不为 NULL 且 wait->wait 已初始化 |
|
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 |
等待的等待队列句柄 |
不为 NULL 且 wait->wait 已初始化 |
|
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 |
等待的等待队列句柄 |
不为 NULL 且 wait->wait 已初始化 |
|
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 |
等待的等待队列句柄 |
不为 NULL 且 wait->wait 已初始化 |
|
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 |
待唤醒的等待队列句柄 |
不为 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 |
待唤醒的等待队列句柄 |
不为 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 |
待销毁的等待队列句柄 |
不为 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