Mutex#

Mutex 提供互斥锁功能,用于保护临界区资源,确保同一时刻仅有一个任务访问共享资源,支持永久等待、限时等待、可中断等待与不等待等多种加锁方式。该模块封装底层操作系统互斥锁服务,向上提供统一的初始化、加锁、解锁、查询与销毁接口。

模块公共头文件

#include "lock/osal_mutex.h"

接口清单#

接口名称

功能简述

osal_mutex_init

初始化指定的互斥锁,使其进入可用状态

osal_mutex_lock

获取互斥锁,独占锁定,不可用则阻塞等待

osal_mutex_lock_timeout

在指定超时时间内尝试获取互斥锁

osal_mutex_lock_interruptible

获取互斥锁,等待期间可被信号中断

osal_mutex_trylock

尝试获取互斥锁,不等待

osal_mutex_unlock

释放当前任务持有的互斥锁

osal_mutex_is_locked

查询指定互斥锁当前的锁定状态

osal_mutex_destroy

销毁指定的互斥锁,释放其占用资源

Functions#

osal_mutex_init #

int osal_mutex_init(osal_mutex *mutex)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 初始化指定的互斥锁,使其进入可用状态。

  • 初始化后的互斥锁可用于保护临界区资源的互斥访问。

  • 是使用互斥锁生命周期中的第一个步骤。

前置条件

  • 调用时序约束:当前接口为互斥锁使用的起始步骤,使用互斥锁前必须先调用本接口完成初始化。

  • 依赖关系:当前接口依赖底层操作系统互斥锁服务与内存分配能力可用。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待初始化的互斥锁指针

不为 NULL,且未被初始化过

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

初始化成功

互斥锁初始化成功

OSAL_FAILURE:-1

初始化失败

mutex 为 NULL、已初始化或内存分配失败

参考案例

  • src/middleware/utils/dfx/log_file/log_file.c

  • src/open_source/lwip/lwip_adapter/liteos_207/src/arch/sys_arch.c

  • src/protocol/wifi/source/host/hmac/hmac_dfx.c

osal_mutex_lock #

int osal_mutex_lock(osal_mutex *mutex)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 获取指定的互斥锁,对互斥锁进行独占锁定。

  • 若互斥锁不可用则阻塞等待,直到获取成功。

  • 用于保护临界区,确保同一时刻仅一个任务访问共享资源。

前置条件

  • 调用时序约束:当前接口必须在 osal_mutex_init() 成功返回后调用。

  • 上下文限制:当前接口可能阻塞睡眠,禁止在中断上下文调用;获取的互斥锁必须由同一任务释放,禁止递归加锁。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待获取的互斥锁指针

不为 NULL,且已通过 osal_mutex_init() 初始化

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

获取互斥锁成功

成功锁定互斥锁

OSAL_FAILURE:-1

获取互斥锁失败

mutex 为 NULL 或内部句柄为空

参考案例

  • src/protocol/wifi/source/host/hmac/hmac_sta_pm.c

  • src/open_source/lwip/lwip_adapter/liteos_207/src/arch/sys_arch.c

  • src/protocol/wifi/source/host/hmac/hmac_dfx.c

osal_mutex_lock_timeout #

int osal_mutex_lock_timeout(osal_mutex *mutex, unsigned int timeout)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 在指定超时时间内尝试获取互斥锁。

  • 若互斥锁在超时时间内可用则获取成功,否则超时返回失败。

  • 支持永久等待与限时等待两种模式。

前置条件

  • 调用时序约束:当前接口必须在 osal_mutex_init() 成功返回后调用。

  • 上下文限制:当前接口可能阻塞睡眠,禁止在中断上下文调用。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待获取的互斥锁指针

不为 NULL,且已通过 osal_mutex_init() 初始化

timeout

unsigned int

超时等待时间(毫秒)

OSAL_MUTEX_WAIT_FOREVER:-1 表示永久等待;
其他数值为超时毫秒数。

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

获取互斥锁成功

在超时时间内成功锁定互斥锁

OSAL_FAILURE:-1

获取互斥锁失败

mutex 为 NULL 或超时未获取到互斥锁

参考案例

  • src/middleware/utils/at/at_wifi_cmd/at/at_register.c

  • src/middleware/services/wifi_service/wpa/osdep/osdep_osal.c

osal_mutex_lock_interruptible #

int osal_mutex_lock_interruptible(osal_mutex *mutex)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 获取互斥锁,等待期间可被信号中断。

  • 若等待过程中收到信号则返回,不获取互斥锁。

  • 适用于可能被信号打断的加锁场景。

前置条件

  • 调用时序约束:当前接口必须在 osal_mutex_init() 成功返回后调用。

  • 上下文限制:当前接口可能阻塞睡眠,等待期间可被信号中断。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待获取的互斥锁指针

不为 NULL,且已通过 osal_mutex_init() 初始化

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

获取互斥锁成功

成功锁定互斥锁

OSAL_FAILURE:-1

获取互斥锁失败

mutex 为 NULL 或内部句柄为空

OSAL_EINTR:-4

被信号中断

等待过程中被信号中断,未获取互斥锁

osal_mutex_trylock #

int osal_mutex_trylock(osal_mutex *mutex)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 尝试获取互斥锁,不等待。

  • 若互斥锁立即可用则获取成功,否则立即返回失败。

  • 适用于不希望阻塞的加锁场景。

前置条件

  • 调用时序约束:当前接口必须在 osal_mutex_init() 成功返回后调用。

  • 上下文限制:当前接口不等待,不会阻塞睡眠。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待获取的互斥锁指针

不为 NULL,且已通过 osal_mutex_init() 初始化

返回值

返回类型:int

返回值

文字含义

触发场景

TRUE:1

获取互斥锁成功

成功获取互斥锁

FALSE:0

获取互斥锁失败

互斥锁被占用或参数无效

osal_mutex_unlock #

void osal_mutex_unlock(osal_mutex *mutex)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 释放当前任务持有的互斥锁。

  • 解除对互斥锁的独占锁定。

  • 用于离开临界区后释放互斥锁。

前置条件

  • 调用时序约束:当前接口必须在 osal_mutex_lock() 等加锁接口成功获取互斥锁后调用,且由加锁的同一任务释放。

  • 上下文限制:当前接口禁止在中断上下文调用,禁止解锁未被锁定的互斥锁。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待释放的互斥锁指针

不为 NULL,且已通过 osal_mutex_init() 初始化

参考案例

  • src/protocol/wifi/source/host/hmac/hmac_sta_pm.c

  • src/open_source/lwip/lwip_adapter/liteos_207/src/arch/sys_arch.c

  • src/protocol/wifi/source/host/hmac/hmac_dfx.c

osal_mutex_is_locked #

int osal_mutex_is_locked(osal_mutex *mutex)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 查询指定互斥锁当前的锁定状态。

  • 返回互斥锁是否处于锁定状态。

  • 用于在不改变互斥锁状态的前提下获取其锁定信息。

前置条件

  • 调用时序约束:当前接口必须在 osal_mutex_init() 成功返回后调用。

  • 依赖关系:当前接口依赖底层操作系统提供互斥锁状态查询能力。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待查询的互斥锁指针

不为 NULL,且已通过 osal_mutex_init() 初始化

返回值

返回类型:int

返回值

文字含义

触发场景

1

互斥锁已锁定

互斥锁处于锁定状态

0

互斥锁未锁定

互斥锁处于未锁定状态

OSAL_FAILURE:-1

查询失败

mutex 为 NULL 或内部句柄为空

osal_mutex_destroy #

void osal_mutex_destroy(osal_mutex *mutex)

声明头文件

#include "lock/osal_mutex.h"

功能说明

  • 销毁指定的互斥锁,释放其占用的资源。

  • 互斥锁销毁后不可再用于加锁/解锁操作。

  • 是使用互斥锁生命周期中的最后一个步骤。

前置条件

  • 调用时序约束:当前接口必须在互斥锁不再被使用(已解锁)时调用,模块退出时须调用以避免内存泄漏。

  • 依赖关系:当前接口调用后互斥锁指针应由调用方置空。

入参

名称

参数类型

说明

约束取值范围

mutex

osal_mutex *

待销毁的互斥锁指针

不为 NULL,且已通过 osal_mutex_init() 初始化

参考案例

  • src/middleware/utils/dfx/log_file/log_file.c

  • src/protocol/wifi/source/host/hmac/hmac_dfx.c

Structures#

osal_mutex #

typedef struct {
    void *mutex;
} osal_mutex;

成员说明

成员名称

数据类型

描述

mutex

void *

互斥锁内部句柄指针

Macros#

OSAL_MUTEX_WAIT_FOREVER #

#define OSAL_MUTEX_WAIT_FOREVER (-1)