# 互斥锁

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

互斥锁（Mutex）是多线程编程中的一种同步机制，用于避免多个线程同时访问同一共享资源（如全局变量）而导致的数据竞争问题。

它通过对访问共享资源的临界区进行互斥保护，保证同一时刻只有一个线程能够进入临界区，从而实现对关键代码的保护，使多线程能够以受控、有序的方式访问共享资源。

# 互斥锁API

## 头文件

*qosa_sys.h*

## 函数概览

| **函数** | **说明** |
| --- | --- |
| *qosa_mutex_create()* | 创建递归互斥锁 |
| *qosa_mutex_lock()* | 获取互斥锁（支持超时设置） |
| *qosa_mutex_try_lock()* | 以非阻塞的方式尝试获取互斥锁 |
| *qosa_mutex_unlock()* | 释放互斥锁 |
| *qosa_mutex_delete()* | 删除互斥锁 |

## 函数详解

### qosa_mutex_create

- **功能描述**  
  创建递归互斥锁。

- **函数原型**

```c
int qosa_mutex_create(qosa_mutex_t *mutexRef)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *mutexRef* | 输出 | qosa_mutex_t * | 指向互斥锁句柄的指针 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MUTEX_INVALID_ERR*：互斥锁参数无效  
  *QOSA_ERROR_MUTEX_CREATE_ERR*：互斥锁创建失败

### qosa_mutex_lock

- **功能描述**  
  获取互斥锁（支持超时设置）。

- **函数原型**

```c
int qosa_mutex_lock(qosa_mutex_t mutexRef, qosa_uint32_t timeout)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *mutexRef* | 输入 | qosa_mutex_t | 互斥锁句柄 |
| *timeout* | 输入 | qosa_uint32_t | 超时时间。单位：毫秒<br>*QOSA_WAIT_FOREVER*：无限等待<br>*QOSA_NO_WAIT*：不等待 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MUTEX_INVALID_ERR*：互斥锁参数无效  
  *QOSA_ERROR_MUTEX_EBUSY_ERR*：互斥锁已被占用  
  *QOSA_ERROR_MUTEX_LOCK_ERR*：互斥锁获取失败

### qosa_mutex_try_lock

- **功能描述**  
  以非阻塞的方式尝试获取互斥锁。函数执行完成后立即返回结果。

- **函数原型**

```c
int qosa_mutex_try_lock(qosa_mutex_t mutexRef)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *mutexRef* | 输入 | qosa_mutex_t | 互斥锁句柄 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MUTEX_INVALID_ERR*：互斥锁参数无效  
  *QOSA_ERROR_MUTEX_EBUSY_ERR*：互斥锁已被占用  
  *QOSA_ERROR_MUTEX_LOCK_ERR*：互斥锁获取失败

### qosa_mutex_unlock

- **功能描述**  
  释放互斥锁。

- **函数原型**

```c
int qosa_mutex_unlock(qosa_mutex_t mutexRef)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *mutexRef* | 输入 | qosa_mutex_t | 互斥锁句柄 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MUTEX_INVALID_ERR*：互斥锁参数无效  
  *QOSA_ERROR_MUTEX_UNLOCK_ERR*：互斥锁解锁失败

### qosa_mutex_delete

- **功能描述**  
  删除互斥锁，并释放资源。

- **函数原型**

```c
int qosa_mutex_delete(qosa_mutex_t mutexRef)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *mutexRef* | 输入 | qosa_mutex_t | 互斥锁句柄 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MUTEX_INVALID_ERR*：互斥锁参数无效  
  *QOSA_ERROR_MUTEX_DELETE_ERR*：互斥锁删除失败

## 枚举定义

### qosa_errcode_os_e

错误码枚举定义如下：

```c
typedef enum
{
    QOSA_ERROR_OK = 0,                                        
    ...
    QOSA_ERROR_MUTEX_CREATE_ERR = 100 | QOSA_ERRCODE_OS_BASE, 
    QOSA_ERROR_MUTEX_LOCK_ERR,                                
    QOSA_ERROR_MUTEX_EBUSY_ERR,                               
    QOSA_ERROR_MUTEX_INVALID_ERR,                             
    QOSA_ERROR_MUTEX_UNLOCK_ERR,                              
    QOSA_ERROR_MUTEX_DELETE_ERR,                              
    ...
}qosa_errcode_os_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_ERROR_OK* | 函数执行成功 |
| *QOSA_ERROR_MUTEX_CREATE_ERR* | 互斥锁创建失败 |
| *QOSA_ERROR_MUTEX_LOCK_ERR* | 互斥锁获取失败 |
| *QOSA_ERROR_MUTEX_EBUSY_ERR* | 互斥锁已被占用 |
| *QOSA_ERROR_MUTEX_INVALID_ERR* | 互斥锁参数无效 |
| *QOSA_ERROR_MUTEX_UNLOCK_ERR* | 互斥锁解锁失败 |
| *QOSA_ERROR_MUTEX_DELETE_ERR* | 互斥锁删除失败 |

# 应用逻辑流程图

```{figure} images/board_DiVXwgVRehRWXbbCKPuccFqiniJ.jpg
:align: center
:alt: image
```

# 示例代码

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/sync_comm/mutex/mutex_demo.c 。