1# condition_variable.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 **condition_variable.h** file declares the condition variable APIs in C. 13 14**Library**: libffrt.z.so 15 16**System capability**: SystemCapability.Resourceschedule.Ffrt.Core 17 18**Since**: 10 19 20**Related module**: [FFRT](capi-ffrt.md) 21 22## Summary 23 24### Function 25 26| Name| Description| 27| -- | -- | 28| [FFRT_C_API int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr)](#ffrt_cond_init) | Initializes a condition variable.| 29| [FFRT_C_API int ffrt_cond_signal(ffrt_cond_t* cond)](#ffrt_cond_signal) | Unblocks at least one of the threads that are blocked on a condition variable.| 30| [FFRT_C_API int ffrt_cond_broadcast(ffrt_cond_t* cond)](#ffrt_cond_broadcast) | Unblocks all threads currently blocked on a condition variable.| 31| [FFRT_C_API int ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex)](#ffrt_cond_wait) | Blocks the calling thread on a condition variable.| 32| [FFRT_C_API int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point)](#ffrt_cond_timedwait) | Blocks the calling thread on a condition variable for a given duration. If **ffrt_cond_signal** or **ffrt_cond_broadcast** is not called to unblock the thread when the maximum wait time is reached, the thread is automatically unblocked.| 33| [FFRT_C_API int ffrt_cond_destroy(ffrt_cond_t* cond)](#ffrt_cond_destroy) | Destroys a condition variable.| 34 35## Function Description 36 37### ffrt_cond_init() 38 39``` 40FFRT_C_API int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr) 41``` 42 43**Description** 44 45Initializes a condition variable. 46 47**Since**: 10 48 49 50**Parameters** 51 52| Name| Description| 53| -- | -- | 54| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | Pointer to the condition variable.| 55| [const ffrt_condattr_t](capi-ffrt-ffrt-condattr-t.md)* attr | Pointer to the condition variable attribute.| 56 57**Returns** 58 59| Type| Description| 60| -- | -- | 61| FFRT_C_API int | Returns **ffrt_success** if the condition variable is initialized;<br> returns **ffrt_error_inval** otherwise.| 62 63### ffrt_cond_signal() 64 65``` 66FFRT_C_API int ffrt_cond_signal(ffrt_cond_t* cond) 67``` 68 69**Description** 70 71Unblocks at least one of the threads that are blocked on a condition variable. 72 73**Since**: 10 74 75 76**Parameters** 77 78| Name| Description| 79| -- | -- | 80| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | Pointer to the condition variable.| 81 82**Returns** 83 84| Type| Description| 85| -- | -- | 86| FFRT_C_API int | Returns **ffrt_success** if at least one of the threads is unblocked;<br> returns **ffrt_error_inval** otherwise.| 87 88### ffrt_cond_broadcast() 89 90``` 91FFRT_C_API int ffrt_cond_broadcast(ffrt_cond_t* cond) 92``` 93 94**Description** 95 96Unblocks all threads currently blocked on a condition variable. 97 98**Since**: 10 99 100 101**Parameters** 102 103| Name| Description| 104| -- | -- | 105| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | Pointer to the condition variable.| 106 107**Returns** 108 109| Type| Description| 110| -- | -- | 111| FFRT_C_API int | Returns **ffrt_success** if all threads are unblocked;<br> returns **ffrt_error_inval** otherwise.| 112 113### ffrt_cond_wait() 114 115``` 116FFRT_C_API int ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex) 117``` 118 119**Description** 120 121Blocks the calling thread on a condition variable. 122 123**Since**: 10 124 125 126**Parameters** 127 128| Name| Description| 129| -- | -- | 130| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | Pointer to the condition variable.| 131| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | Pointer to the mutex.| 132 133**Returns** 134 135| Type| Description| 136| -- | -- | 137| FFRT_C_API int | Returns **ffrt_success** if the thread is unblocked after being blocked;<br> returns **ffrt_error_inval** otherwise.| 138 139### ffrt_cond_timedwait() 140 141``` 142FFRT_C_API int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point) 143``` 144 145**Description** 146 147Blocks the calling thread on a condition variable for a given duration. If **ffrt_cond_signal** or **ffrt_cond_broadcast** is not called to unblock the thread when the maximum wait time is reached, the thread is automatically unblocked. 148 149**Since**: 10 150 151 152**Parameters** 153 154| Name| Description| 155| -- | -- | 156| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | Pointer to the condition variable.| 157| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | Pointer to the mutex.| 158| const struct timespec* time_point | Pointer to the maximum duration that the thread is blocked.| 159 160**Returns** 161 162| Type| Description| 163| -- | -- | 164| FFRT_C_API int | Returns **ffrt_success** if the thread is unblocked after being blocked;<br> returns **ffrt_error_timedout** if the wait times out;<br> returns **ffrt_error_inval** if the wait fails.| 165 166### ffrt_cond_destroy() 167 168``` 169FFRT_C_API int ffrt_cond_destroy(ffrt_cond_t* cond) 170``` 171 172**Description** 173 174Destroys a condition variable. 175 176**Since**: 10 177 178 179**Parameters** 180 181| Name| Description| 182| -- | -- | 183| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | Pointer to the condition variable.| 184 185**Returns** 186 187| Type| Description| 188| -- | -- | 189| FFRT_C_API int | Returns **ffrt_success** if the condition variable is destroyed successfully;<br>returns **ffrt_error_inval** otherwise.| 190