更新日期: 2022/06/01 来源: https://gitee.com/weharmony/kernel_liteos_a_note
los_rwlock.h
浏览该文件的文档.
1/*
2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
3 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice, this list of
9 * conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
12 * of conditions and the following disclaimer in the documentation and/or other materials
13 * provided with the distribution.
14 *
15 * 3. Neither the name of the copyright holder nor the names of its contributors may be used
16 * to endorse or promote products derived from this software without specific prior written
17 * permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
26 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
28 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
29 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 */
31
32/**
33 * @defgroup los_rwlock Rwlock
34 * @ingroup kernel
35 */
36
37#ifndef _LOS_RWLOCK_H
38#define _LOS_RWLOCK_H
39
40#include "los_base.h"
41
42#ifdef __cplusplus
43#if __cplusplus
44extern "C" {
45#endif /* __cplusplus */
46#endif /* __cplusplus */
47
48/**
49 * @ingroup los_rwlock
50 * Rwlock object.
51 */
52typedef struct OsRwlock {//读写锁
53 INT32 magic:24; /**< Magic number | 魔法数字 为什么要用魔法数字 ? */
54 INT32 rwCount:8; /**< Times of locking the rwlock, rwCount > 0 when rwkick is read mode, rwCount < 0
55 when the rwlock is write mode, rwCount = 0 when the lock is free.
56 大于0时为读模式 , 小于0时为写模式 等于0为自由模式
57 rwCount为读锁和写锁的数量,注意它们并不是此消彼长的行为模式*/
58 VOID *writeOwner; /**< The current write thread that is locking the rwlock | 拥有写权限的任务*/
59 LOS_DL_LIST readList; /**< Read waiting list | 等待读操作的任务链表*/
60 LOS_DL_LIST writeList; /**< Write waiting list | 等待写操作的任务链表*/
62
63extern BOOL LOS_RwlockIsValid(const LosRwlock *rwlock);
64
65/**
66 * @ingroup los_rwlock
67 * @brief Init a rwlock.
68 *
69 * @par Description:
70 * This API is used to Init a rwlock. A rwlock handle is assigned to rwlockHandle when the rwlock is init successfully.
71 * Return LOS_OK on creating successful, return specific error code otherwise.
72 * @param rwlock [IN] Handle pointer of the successfully init rwlock.
73 *
74 * @retval #LOS_EINVAL The rwlock pointer is NULL.
75 * @retval #LOS_EPERM Multiply initialization.
76 * @retval #LOS_OK The rwlock is successfully created.
77 * @par Dependency:
78 * <ul><li>los_rwlock.h: the header file that contains the API declaration.</li></ul>
79 * @see LOS_RwlockDestroy
80 */
81extern UINT32 LOS_RwlockInit(LosRwlock *rwlock);
82
83/**
84 * @ingroup los_rwlock
85 * @brief Destroy a rwlock.
86 *
87 * @par Description:
88 * This API is used to delete a specified rwlock. Return LOS_OK on deleting successfully, return specific error code
89 * otherwise.
90 * @attention
91 * <ul>
92 * <li>The specific rwlock should be created firstly.</li>
93 * <li>The rwlock can be deleted successfully only if no other tasks pend on it.</li>
94 * </ul>
95 *
96 * @param rwlock [IN] Handle of the rwlock to be deleted.
97 *
98 * @retval #LOS_EINVAL The rwlock pointer is NULL.
99 * @retval #LOS_EBUSY Tasks pended on this rwlock.
100 * @retval #LOS_EBADF The lock has been destroyed or broken.
101 * @retval #LOS_OK The rwlock is successfully deleted.
102 * @par Dependency:
103 * <ul><li>los_rwlock.h: the header file that contains the API declaration.</li></ul>
104 * @see LOS_RwlockInit
105 */
106extern UINT32 LOS_RwlockDestroy(LosRwlock *rwlock);
107
108/**
109 * @ingroup los_rwlock
110 * @brief Wait to lock a read lock.
111 *
112 * @par Description:
113 * This API is used to wait for a specified period of time to lock a read lock.
114 * @attention
115 * <ul>
116 * <li>The specific rwlock should be created firstly.</li>
117 * <li>The function fails if the rwlock that is waited on is already locked by another thread when the task scheduling
118 * is disabled.</li>
119 * <li>Do not wait on a rwlock during an interrupt.</li>
120 * <li>The function fails when other tasks have the write lock or there are some task pending on the write list with
121 * the higher priority.</li>
122 * <li>A recursive rwlock can be locked more than once by the same thread.</li>
123 * <li>Do not call this API in software timer callback. </li>
124 * </ul>
125 *
126 * @param rwlock [IN] Handle of the rwlock to be waited on.
127 * @param timeout [IN] Waiting time. The value range is [0, LOS_WAIT_FOREVER](unit: Tick).
128 *
129 * @retval #LOS_EINVAL The rwlock pointer is NULL, The timeout is zero or Lock status error.
130 * @retval #LOS_EINTR The rwlock is being locked during an interrupt.
131 * @retval #LOS_EBADF The lock has been destroyed or broken.
132 * @retval #LOS_EDEADLK Rwlock error check failed or System locked task scheduling.
133 * @retval #LOS_ETIMEDOUT The rwlock waiting times out.
134 * @retval #LOS_EPERM The rwlock is used in system tasks.
135 * @retval #LOS_OK The rwlock is successfully locked.
136 * @par Dependency:
137 * <ul><li>los_rwlock.h: the header file that contains the API declaration.</li></ul>
138 * @see LOS_RwlockInit | LOS_RwlockUnLock
139 */
140extern UINT32 LOS_RwlockRdLock(LosRwlock *rwlock, UINT32 timeout);
141
142/**
143 * @ingroup los_rwlock
144 * @brief Try wait to lock a read lock.
145 *
146 * @par Description:
147 * This API is used to wait for a specified period of time to lock a read lock.
148 * @attention
149 * <ul>
150 * <li>The specific rwlock should be created firstly.</li>
151 * <li>The function fails if the rwlock that is waited on is already locked by another thread when the task scheduling
152 * is disabled.</li>
153 * <li>Do not wait on a rwlock during an interrupt.</li>
154 * <li>The function fails when other tasks have the write lock or there are some task pending on the write list with
155 * the higher priority.</li>
156 * <li>A recursive rwlock can be locked more than once by the same thread.</li>
157 * <li>Do not call this API in software timer callback. </li>
158 * </ul>
159 *
160 * @param rwlock [IN] Handle of the rwlock to be waited on.
161 *
162 * @retval #LOS_EINVAL The rwlock pointer is NULL or Lock status error.
163 * @retval #LOS_EINTR The rwlock is being locked during an interrupt.
164 * @retval #LOS_EBUSY Fail to get the rwlock, the rwlock has been used.
165 * @retval #LOS_EBADF The lock has been destroyed or broken.
166 * @retval #LOS_EDEADLK rwlock error check failed or System locked task scheduling.
167 * @retval #LOS_ETIMEDOUT The rwlock waiting times out.
168 * @retval #LOS_EPERM The rwlock is used in system tasks.
169 * @retval #LOS_OK The rwlock is successfully locked.
170 * @par Dependency:
171 * <ul><li>los_rwlock.h: the header file that contains the API declaration.</li></ul>
172 * @see LOS_RwlockInit | LOS_RwlockUnLock
173 */
174extern UINT32 LOS_RwlockTryRdLock(LosRwlock *rwlock);
175
176/**
177 * @ingroup los_rwlock
178 * @brief Wait to lock a write lock.
179 *
180 * @par Description:
181 * This API is used to wait for a specified period of time to lock a write lock.
182 * @attention
183 * <ul>
184 * <li>The specific rwlock should be created firstly.</li>
185 * <li>The function fails if the rwlock that is waited on is already locked by another thread when
186 * the task scheduling.</li>
187 * is disabled.</li>
188 * <li>Do not wait on a rwlock during an interrupt.</li>
189 * <li>The funtion fails when other tasks have the read or write lock.</li>
190 * <li>A recursive rwlock can be locked more than once by the same thread.</li>
191 * <li>Do not call this API in software timer callback. </li>
192 * </ul>
193 *
194 * @param rwlock [IN] Handle of the rwlock to be waited on.
195 * @param timeout [IN] Waiting time. The value range is [0, LOS_WAIT_FOREVER](unit: Tick).
196 *
197 * @retval #LOS_EINVAL The rwlock pointer is NULL, The timeout is zero or Lock status error.
198 * @retval #LOS_EINTR The rwlock is being locked during an interrupt.
199 * @retval #LOS_EBADF The lock has been destroyed or broken.
200 * @retval #LOS_EDEADLK Rwlock error check failed or System locked task scheduling.
201 * @retval #LOS_ETIMEDOUT The rwlock waiting times out.
202 * @retval #LOS_EPERM The rwlock is used in system tasks.
203 * @retval #LOS_OK The rwlock is successfully locked.
204 * @par Dependency:
205 * <ul><li>los_rwlock.h: the header file that contains the API declaration.</li></ul>
206 * @see LOS_MuxInit | LOS_MuxUnlock
207 */
208extern UINT32 LOS_RwlockWrLock(LosRwlock *rwlock, UINT32 timeout);
209
210/**
211 * @ingroup los_rwlock
212 * @brief Try wait to lock a write lock.
213 *
214 * @par Description:
215 * This API is used to wait for a specified period of time to lock a write lock.
216 * @attention
217 * <ul>
218 * <li>The specific rwlock should be created firstly.</li>
219 * <li>The function fails if the rwlock that is waited on is already locked by another thread
220 * when the task scheduling.</li>
221 * is disabled.</li>
222 * <li>Do not wait on a rwlock during an interrupt.</li>
223 * <li>The funtion fails when other tasks have the read or write lock.</li>
224 * <li>A recursive rwlock can be locked more than once by the same thread.</li>
225 * <li>Do not call this API in software timer callback. </li>
226 * </ul>
227 *
228 * @param rwlock [IN] Handle of the rwlock to be waited on.
229 *
230 * @retval #LOS_EINVAL The rwlock pointer is NULL or Lock status error.
231 * @retval #LOS_EINTR The rwlock is being locked during an interrupt.
232 * @retval #LOS_EBUSY Fail to get the rwlock, the rwlock has been used.
233 * @retval #LOS_EBADF The lock has been destroyed or broken.
234 * @retval #LOS_EDEADLK rwlock error check failed or System locked task scheduling.
235 * @retval #LOS_ETIMEDOUT The rwlock waiting times out.
236 * @retval #LOS_EPERM The rwlock is used in system tasks.
237 * @retval #LOS_OK The rwlock is successfully locked.
238 * @par Dependency:
239 * <ul><li>los_rwlock.h: the header file that contains the API declaration.</li></ul>
240 * @see LOS_RwlockInit | LOS_RwlockUnLock
241 */
242extern UINT32 LOS_RwlockTryWrLock(LosRwlock *rwlock);
243
244/**
245 * @ingroup los_rwlock
246 * @brief Release a rwlock.
247 *
248 * @par Description:
249 * This API is used to release a specified rwlock.
250 * @attention
251 * <ul>
252 * <li>The specific rwlock should be created firstly.</li>
253 * <li>Do not release a rwlock during an interrupt.</li>
254 * <li>When the write list is null and the read list is not null, all the task pending on the read list
255 * will be waken.<li>
256 * <li>When the write list is not null and the read list is null, the task pending on the read list will be
257 * waken by the priority.<li>
258 * <li>When the write list and the read list are not null, all the task pending on the both list will be waken
259 * by the priority.<li>
260 * If the task on the write list has the same priority as the task on the read list, the forth will
261 * be waken.<li>
262 * <li>If a recursive rwlock is locked for many times, it must be unlocked for the same times to be
263 * released.</li>
264 * </ul>
265 *
266 * @param rwlock [IN] Handle of the rwlock to be released.
267 *
268 * @retval #LOS_EINVAL The rwlock pointer is NULL, The timeout is zero or Lock status error.
269 * @retval #LOS_EINTR The rwlock is being locked during an interrupt.
270 * @retval #LOS_EPERM The rwlock is not locked or has been used.
271 * @retval #LOS_EBADF The lock has been destroyed or broken.
272 * @retval #LOS_EDEADLK rwlock error check failed or System locked task scheduling.
273 * @retval #LOS_ETIMEDOUT The rwlock waiting times out.
274 * @retval #LOS_EPERM The rwlock is used in system tasks.
275 * @retval #LOS_OK The rwlock is successfully locked.
276 * @par Dependency:
277 * <ul><li>los_mux.h: the header file that contains the API declaration.</li></ul>
278 * @see LOS_RwlockInit | LOS_ReadLock | LOS_WriteLock
279 */
280extern UINT32 LOS_RwlockUnLock(LosRwlock *rwlock);
281
282#ifdef __cplusplus
283#if __cplusplus
284}
285#endif
286#endif /* __cplusplus */
287
288#endif /* _LOS_MUX_H */
UINT32 LOS_RwlockUnLock(LosRwlock *rwlock)
Release a rwlock.
Definition: los_rwlock.c:482
struct OsRwlock LosRwlock
UINT32 LOS_RwlockTryRdLock(LosRwlock *rwlock)
Try wait to lock a read lock.
Definition: los_rwlock.c:336
UINT32 LOS_RwlockInit(LosRwlock *rwlock)
Init a rwlock.
Definition: los_rwlock.c:79
UINT32 LOS_RwlockWrLock(LosRwlock *rwlock, UINT32 timeout)
Wait to lock a write lock.
Definition: los_rwlock.c:351
UINT32 LOS_RwlockRdLock(LosRwlock *rwlock, UINT32 timeout)
Wait to lock a read lock.
Definition: los_rwlock.c:321
UINT32 LOS_RwlockDestroy(LosRwlock *rwlock)
Destroy a rwlock.
Definition: los_rwlock.c:102
UINT32 LOS_RwlockTryWrLock(LosRwlock *rwlock)
Try wait to lock a write lock.
Definition: los_rwlock.c:366
BOOL LOS_RwlockIsValid(const LosRwlock *rwlock)
判断读写锁有效性
Definition: los_rwlock.c:70
signed int INT32
Definition: los_typedef.h:60
unsigned int UINT32
Definition: los_typedef.h:57
size_t BOOL
Definition: los_typedef.h:88
INT32 magic
Definition: los_rwlock.h:53
LOS_DL_LIST readList
Definition: los_rwlock.h:59
VOID * writeOwner
Definition: los_rwlock.h:58
INT32 rwCount
Definition: los_rwlock.h:54
LOS_DL_LIST writeList
Definition: los_rwlock.h:60