• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# mutex.h
2
3<!--Kit: Function Flow Runtime Kit-->
4<!--Subsystem: Resourceschedule-->
5<!--Owner: @chuchihtung; @yanleo-->
6<!--Designer: @geoffrey_guo; @huangyouzhong-->
7<!--Tester: @lotsof; @sunxuhao-->
8<!--Adviser: @foryourself-->
9
10## Overview
11
12The **mutex.h** file declares the mutex APIs in C.
13
14**File to include**: <ffrt/mutex.h>
15
16**Library**: libffrt.z.so
17
18**System capability**: SystemCapability.Resourceschedule.Ffrt.Core
19
20**Since**: 10
21
22**Related module**: [FFRT](capi-ffrt.md)
23
24## Summary
25
26### Function
27
28| Name| Description|
29| -- | -- |
30| [FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr)](#ffrt_mutexattr_init) | Initializes the mutex attribute.|
31| [FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type)](#ffrt_mutexattr_settype) | Sets the mutex attribute type.|
32| [FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type)](#ffrt_mutexattr_gettype) | Obtains the mutex type.|
33| [FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr)](#ffrt_mutexattr_destroy) | Destroys the mutex attribute. This API needs to be called by users.|
34| [FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr)](#ffrt_mutex_init) | Initializes a mutex.|
35| [FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex)](#ffrt_mutex_lock) | Locks a mutex.|
36| [FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex)](#ffrt_mutex_unlock) | Unlocks a mutex.|
37| [FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex)](#ffrt_mutex_trylock) | Attempts to lock a mutex.|
38| [FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex)](#ffrt_mutex_destroy) | Destroys a mutex.|
39
40## Function Description
41
42### ffrt_mutexattr_init()
43
44```
45FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr)
46```
47
48**Description**
49
50Initializes the mutex attribute.
51
52**Since**: 12
53
54
55**Parameters**
56
57| Name| Description|
58| -- | -- |
59| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | Pointer to the mutex attribute.|
60
61**Returns**
62
63| Type| Description|
64| -- | -- |
65| FFRT_C_API int | Returns **ffrt_success** if the mutex attribute is initialized;<br>          returns **ffrt_error_inval** otherwise.|
66
67### ffrt_mutexattr_settype()
68
69```
70FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type)
71```
72
73**Description**
74
75Sets the mutex attribute type.
76
77**Since**: 12
78
79
80**Parameters**
81
82| Name| Description|
83| -- | -- |
84| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | Pointer to the mutex attribute.|
85| int type | Mutex type.|
86
87**Returns**
88
89| Type| Description|
90| -- | -- |
91| FFRT_C_API int | Returns **ffrt_success** if the mutex attribute type is set;<br>          returns **ffrt_error_inval** if the pointer to the mutex attribute is null<br>          or the mutex is not of the **ffrt_mutex_normal** or **ffrt_mutex_recursive** type.|
92
93### ffrt_mutexattr_gettype()
94
95```
96FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type)
97```
98
99**Description**
100
101Obtains the mutex type.
102
103**Since**: 12
104
105
106**Parameters**
107
108| Name| Description|
109| -- | -- |
110| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | Pointer to the mutex attribute.|
111| int* type | Pointer to the mutex type.|
112
113**Returns**
114
115| Type| Description|
116| -- | -- |
117| FFRT_C_API int | Returns **ffrt_success** if the mutex type is obtained;<br>          returns **ffrt_error_inval** if the pointer to the mutex attribute or mutex type is null.|
118
119### ffrt_mutexattr_destroy()
120
121```
122FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr)
123```
124
125**Description**
126
127Destroys the mutex attribute. This API needs to be called by users.
128
129**Since**: 12
130
131
132**Parameters**
133
134| Name| Description|
135| -- | -- |
136| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | Pointer to the mutex attribute.|
137
138**Returns**
139
140| Type| Description|
141| -- | -- |
142| FFRT_C_API int | Returns **ffrt_success** if the mutex attribute is destroyed;<br>          returns **ffrt_error_inval** otherwise.|
143
144### ffrt_mutex_init()
145
146```
147FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr)
148```
149
150**Description**
151
152Initializes a mutex.
153
154**Since**: 10
155
156
157**Parameters**
158
159| Name| Description|
160| -- | -- |
161| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | Pointer to the mutex.|
162| [const ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | Pointer to the mutex attribute.|
163
164**Returns**
165
166| Type| Description|
167| -- | -- |
168| FFRT_C_API int | Returns **ffrt_success** if the mutex is initialized;<br>          returns **ffrt_error_inval** otherwise.|
169
170### ffrt_mutex_lock()
171
172```
173FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex)
174```
175
176**Description**
177
178Locks a mutex.
179
180**Since**: 10
181
182
183**Parameters**
184
185| Name| Description|
186| -- | -- |
187| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | Pointer to the mutex.|
188
189**Returns**
190
191| Type| Description|
192| -- | -- |
193| FFRT_C_API int | Returns **ffrt_success** if the mutex is locked;<br>          returns **ffrt_error_inval** or blocks the calling thread otherwise.|
194
195### ffrt_mutex_unlock()
196
197```
198FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex)
199```
200
201**Description**
202
203Unlocks a mutex.
204
205**Since**: 10
206
207
208**Parameters**
209
210| Name| Description|
211| -- | -- |
212| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | Pointer to the mutex.|
213
214**Returns**
215
216| Type| Description|
217| -- | -- |
218| FFRT_C_API int | Returns **ffrt_success** if the mutex is unlocked;<br>          returns **ffrt_error_inval** otherwise.|
219
220### ffrt_mutex_trylock()
221
222```
223FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex)
224```
225
226**Description**
227
228Attempts to lock a mutex.
229
230**Since**: 10
231
232
233**Parameters**
234
235| Name| Description|
236| -- | -- |
237| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | Pointer to the mutex.|
238
239**Returns**
240
241| Type| Description|
242| -- | -- |
243| FFRT_C_API int | Returns **ffrt_success** if the mutex is locked;<br>          returns **ffrt_error_inval** or **ffrt_error_busy** otherwise.|
244
245### ffrt_mutex_destroy()
246
247```
248FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex)
249```
250
251**Description**
252
253Destroys a mutex.
254
255**Since**: 10
256
257
258**Parameters**
259
260| Name| Description|
261| -- | -- |
262| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | Pointer to the mutex.|
263
264**Returns**
265
266| Type| Description|
267| -- | -- |
268| FFRT_C_API int | Returns **ffrt_success** if the mutex is destroyed successfully;<br>returns **ffrt_error_inval** otherwise.|
269