已合并
API 参考 8分需求 #154853
mazhabandeng创建于 7月9日
API 参考 8分需求 #154853
已合并
共 27 个文件变更+796-676
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | - C API<!--function-flow-runtime-c--> | 10 | - C API<!--function-flow-runtime-c--> |
| @@ -2,9 +2,9 @@ | |||||||
| 2 | 2 | ||||||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> | ||||
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> | ||||
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> | ||||
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> | ||||
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> | ||||
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> | ||||
| 9 | 9 | ||||||
| 10 | ## 概述 | 10 | ## 概述 | ||||
| @@ -27,12 +27,12 @@ | |||||||
| 27 | 27 | ||||||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | | ||||
| 29 | | -- | -- | | 29 | | -- | -- | | ||||
| 30 | -| [FFRT_C_API int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr)](#ffrt_cond_init) | 初始化条件变量。 | | 30 | +| [FFRT_C_API int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr)](#ffrt_cond_init) | 初始化条件变量。该条件变量不再使用时，必须通过[ffrt_cond_destroy](capi-condition-variable-h.md#ffrt_cond_destroy)销毁。 | | ||||
AA ❌疑似检测出标点符号问题 错误原因：英文右括号后面跟了空格，在中文文档中应该使用中文右括号 建议修改为： 改动建议
  | |||||||
| 31 | -| [FFRT_C_API int ffrt_cond_signal(ffrt_cond_t* cond)](#ffrt_cond_signal) | 唤醒阻塞在条件变量上的一个任务。 | | 31 | +| [FFRT_C_API int ffrt_cond_signal(ffrt_cond_t* cond)](#ffrt_cond_signal) | 唤醒至少一个阻塞在条件变量上的线程。 | | ||||
| 32 | -| [FFRT_C_API int ffrt_cond_broadcast(ffrt_cond_t* cond)](#ffrt_cond_broadcast) | 唤醒阻塞在条件变量上的所有任务。 | | 32 | +| [FFRT_C_API int ffrt_cond_broadcast(ffrt_cond_t* cond)](#ffrt_cond_broadcast) | 唤醒当前阻塞在条件变量上的所有线程。 | | ||||
| 33 | -| [FFRT_C_API int ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex)](#ffrt_cond_wait) | 条件变量等待函数，条件变量不满足时阻塞当前任务。 | | 33 | +| [FFRT_C_API int ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex)](#ffrt_cond_wait) | 将调用线程阻塞在条件变量上。调用线程在进入时必须持有该mutex。阻塞期间会原子地释放该mutex，并在函数返回前重新获取，因此调用方在唤醒时重新获得mutex的所有权。线程由另一个线程调用[ffrt_cond_signal](capi-condition-variable-h.md#ffrt_cond_signal)或[ffrt_cond_broadcast](capi-condition-variable-h.md#ffrt_cond_broadcast)唤醒。调用方需在唤醒后重新检查谓词，以防止虚假唤醒。 | | ||||
| 34 | -| [FFRT_C_API int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point)](#ffrt_cond_timedwait) | 条件变量超时等待函数，条件变量不满足时阻塞当前任务，超时等待返回。如果达到最大等待时间点时没有调用ffrt_cond_signal或ffrt_cond_broadcast函数解除线程阻塞，则线程会被自动解除阻塞。 | | 34 | +| [FFRT_C_API int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point)](#ffrt_cond_timedwait) | 将调用线程阻塞至给定的时间点。如果在到达`time_point`前没有调用[ffrt_cond_signal](capi-condition-variable-h.md#ffrt_cond_signal)或[ffrt_cond_broadcast](capi-condition-variable-h.md#ffrt_cond_broadcast)来唤醒线程，线程会被自动唤醒。 | | ||||
| 35 | -| [FFRT_C_API int ffrt_cond_destroy(ffrt_cond_t* cond)](#ffrt_cond_destroy) | 销毁条件变量。 | | 35 | +| [FFRT_C_API int ffrt_cond_destroy(ffrt_cond_t* cond)](#ffrt_cond_destroy) | 销毁条件变量。该条件变量必须已通过[ffrt_cond_init](capi-condition-variable-h.md#ffrt_cond_init)初始化，且在调用本接口时不得被任何线程引用。 | | ||||
| 36 | 36 | ||||||
| 37 | ## 函数说明 | 37 | ## 函数说明 | ||||
| 38 | 38 | ||||||
| @@ -44,7 +44,7 @@ FFRT_C_API int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr) | |||||||
| 44 | 44 | ||||||
| 45 | **描述** | 45 | **描述** | ||||
| 46 | 46 | ||||||
| 47 | -初始化条件变量。 | 47 | +初始化条件变量。该条件变量不再使用时，必须通过[ffrt_cond_destroy](capi-condition-variable-h.md#ffrt_cond_destroy)销毁。 | ||||
| 48 | 48 | ||||||
| 49 | **起始版本：** 10 | 49 | **起始版本：** 10 | ||||
| 50 | 50 | ||||||
| @@ -52,14 +52,14 @@ FFRT_C_API int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr) | |||||||
| 52 | 52 | ||||||
| 53 | | 参数项 | 描述 | | 53 | | 参数项 | 描述 | | ||||
| 54 | | -- | -- | | 54 | | -- | -- | | ||||
| 55 | -| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 条件变量指针。 | | 55 | +| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 指向条件变量的指针。 | | ||||
| 56 | -| [const ffrt_condattr_t](capi-ffrt-ffrt-condattr-t.md)* attr | 条件变量属性指针。 | | 56 | +| [const ffrt_condattr_t](capi-ffrt-ffrt-condattr-t.md)* attr | 指向条件变量属性的指针。 | | ||||
| 57 | 57 | ||||||
| 58 | **返回：** | 58 | **返回：** | ||||
| 59 | 59 | ||||||
| 60 | | 类型 | 说明 | | 60 | | 类型 | 说明 | | ||||
| 61 | | -- | -- | | 61 | | -- | -- | | ||||
| 62 | -| FFRT_C_API int | 初始化条件变量成功返回ffrt_success，<br> 初始化条件变量失败返回ffrt_error_inval。 | | 62 | +| FFRT_C_API int | 条件变量初始化成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | | ||||
A ❌疑似检测出标点符号问题 错误原因：英文右书名号后面跟了空格，在中文文档中应该使用中文右书名号 建议修改为： 当前建议代码无改动
💡 温馨提示：
请审视上述建议的准确性。若您认为检测结果不合理或属于误报，请通过 反馈通道 告知我们。您的反馈对于提升 AI 检测精度的意义重大，我们将据此持续改进此工具
| |||||||
| 63 | 63 | ||||||
| 64 | ### ffrt_cond_signal() | 64 | ### ffrt_cond_signal() | ||||
| 65 | 65 | ||||||
| @@ -69,7 +69,7 @@ FFRT_C_API int ffrt_cond_signal(ffrt_cond_t* cond) | |||||||
| 69 | 69 | ||||||
| 70 | **描述** | 70 | **描述** | ||||
| 71 | 71 | ||||||
| 72 | -唤醒阻塞在条件变量上的一个任务。 | 72 | +唤醒至少一个阻塞在条件变量上的线程。 | ||||
| 73 | 73 | ||||||
| 74 | **起始版本：** 10 | 74 | **起始版本：** 10 | ||||
| 75 | 75 | ||||||
| @@ -77,13 +77,18 @@ FFRT_C_API int ffrt_cond_signal(ffrt_cond_t* cond) | |||||||
| 77 | 77 | ||||||
| 78 | | 参数项 | 描述 | | 78 | | 参数项 | 描述 | | ||||
| 79 | | -- | -- | | 79 | | -- | -- | | ||||
| 80 | -| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 条件变量指针。 | | 80 | +| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 指向条件变量的指针。 | | ||||
| 81 | 81 | ||||||
| 82 | **返回：** | 82 | **返回：** | ||||
| 83 | 83 | ||||||
| 84 | | 类型 | 说明 | | 84 | | 类型 | 说明 | | ||||
| 85 | | -- | -- | | 85 | | -- | -- | | ||||
| 86 | -| FFRT_C_API int | 唤醒成功返回ffrt_success，<br> 唤醒失败返回ffrt_error_inval。 | | 86 | +| FFRT_C_API int | 线程被唤醒时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | | ||||
| 87 | + | ||||||
| 88 | +**参考：** | ||||||
| 89 | + | ||||||
| 90 | +[ffrt_cond_wait](capi-condition-variable-h.md#ffrt_cond_wait) | ||||||
| 91 | + | ||||||
| 87 | 92 | ||||||
| 88 | ### ffrt_cond_broadcast() | 93 | ### ffrt_cond_broadcast() | ||||
| 89 | 94 | ||||||
| @@ -93,7 +98,7 @@ FFRT_C_API int ffrt_cond_broadcast(ffrt_cond_t* cond) | |||||||
| 93 | 98 | ||||||
| 94 | **描述** | 99 | **描述** | ||||
| 95 | 100 | ||||||
| 96 | -唤醒阻塞在条件变量上的所有任务。 | 101 | +唤醒当前阻塞在条件变量上的所有线程。 | ||||
| 97 | 102 | ||||||
| 98 | **起始版本：** 10 | 103 | **起始版本：** 10 | ||||
| 99 | 104 | ||||||
| @@ -101,13 +106,18 @@ FFRT_C_API int ffrt_cond_broadcast(ffrt_cond_t* cond) | |||||||
| 101 | 106 | ||||||
| 102 | | 参数项 | 描述 | | 107 | | 参数项 | 描述 | | ||||
| 103 | | -- | -- | | 108 | | -- | -- | | ||||
| 104 | -| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 条件变量指针。 | | 109 | +| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 指向条件变量的指针。 | | ||||
| 105 | 110 | ||||||
| 106 | **返回：** | 111 | **返回：** | ||||
| 107 | 112 | ||||||
| 108 | | 类型 | 说明 | | 113 | | 类型 | 说明 | | ||||
| 109 | | -- | -- | | 114 | | -- | -- | | ||||
| 110 | -| FFRT_C_API int | 唤醒成功返回ffrt_success，<br> 唤醒失败返回ffrt_error_inval。 | | 115 | +| FFRT_C_API int | 线程被唤醒时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | | ||||
| 116 | + | ||||||
| 117 | +**参考：** | ||||||
| 118 | + | ||||||
| 119 | +[ffrt_cond_wait](capi-condition-variable-h.md#ffrt_cond_wait) | ||||||
| 120 | + | ||||||
| 111 | 121 | ||||||
| 112 | ### ffrt_cond_wait() | 122 | ### ffrt_cond_wait() | ||||
| 113 | 123 | ||||||
| @@ -117,7 +127,7 @@ FFRT_C_API int ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex) | |||||||
| 117 | 127 | ||||||
| 118 | **描述** | 128 | **描述** | ||||
| 119 | 129 | ||||||
| 120 | -条件变量等待函数，条件变量不满足时阻塞当前任务。 | 130 | +将调用线程阻塞在条件变量上。调用线程在进入时必须持有该mutex。阻塞期间会原子地释放该mutex，并在函数返回前重新获取，因此调用方在唤醒时重新获得mutex的所有权。线程由另一个线程调用[ffrt_cond_signal](capi-condition-variable-h.md#ffrt_cond_signal)或[ffrt_cond_broadcast](capi-condition-variable-h.md#ffrt_cond_broadcast)唤醒。调用方需在唤醒后重新检查谓词，以防止虚假唤醒。 | ||||
| 121 | 131 | ||||||
| 122 | **起始版本：** 10 | 132 | **起始版本：** 10 | ||||
| 123 | 133 | ||||||
| @@ -125,14 +135,23 @@ FFRT_C_API int ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex) | |||||||
| 125 | 135 | ||||||
| 126 | | 参数项 | 描述 | | 136 | | 参数项 | 描述 | | ||||
| 127 | | -- | -- | | 137 | | -- | -- | | ||||
| 128 | -| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 条件变量指针。 | | 138 | +| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 指向条件变量的指针。 | | ||||
| 129 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | mutex指针。 | | 139 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | 指向调用线程持有的mutex的指针。 | | ||||
| 130 | 140 | ||||||
| 131 | **返回：** | 141 | **返回：** | ||||
| 132 | 142 | ||||||
| 133 | | 类型 | 说明 | | 143 | | 类型 | 说明 | | ||||
| 134 | | -- | -- | | 144 | | -- | -- | | ||||
| 135 | -| FFRT_C_API int | 等待后被成功唤醒返回ffrt_success，<br> 等待失败返回ffrt_error_inval。 | | 145 | +| FFRT_C_API int | 阻塞后被成功唤醒时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | | ||||
| 146 | + | ||||||
| 147 | +**参考：** | ||||||
| 148 | + | ||||||
| 149 | +[ffrt_cond_timedwait](capi-condition-variable-h.md#ffrt_cond_timedwait) | ||||||
| 150 | + | ||||||
| 151 | +[ffrt_cond_signal](capi-condition-variable-h.md#ffrt_cond_signal) | ||||||
| 152 | + | ||||||
| 153 | +[ffrt_cond_broadcast](capi-condition-variable-h.md#ffrt_cond_broadcast) | ||||||
| 154 | + | ||||||
| 136 | 155 | ||||||
| 137 | ### ffrt_cond_timedwait() | 156 | ### ffrt_cond_timedwait() | ||||
| 138 | 157 | ||||||
| @@ -142,7 +161,7 @@ FFRT_C_API int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const | |||||||
| 142 | 161 | ||||||
| 143 | **描述** | 162 | **描述** | ||||
| 144 | 163 | ||||||
| 145 | -条件变量超时等待函数，条件变量不满足时阻塞当前任务，超时等待返回。如果达到最大等待时间点时没有调用ffrt_cond_signal或ffrt_cond_broadcast函数解除线程阻塞，则线程会被自动解除阻塞。 | 164 | +将调用线程阻塞至给定的时间点。如果在到达`time_point`前没有调用[ffrt_cond_signal](capi-condition-variable-h.md#ffrt_cond_signal)或[ffrt_cond_broadcast](capi-condition-variable-h.md#ffrt_cond_broadcast)来唤醒线程，线程会被自动唤醒。 | ||||
| 146 | 165 | ||||||
| 147 | **起始版本：** 10 | 166 | **起始版本：** 10 | ||||
| 148 | 167 | ||||||
| @@ -150,15 +169,24 @@ FFRT_C_API int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const | |||||||
| 150 | 169 | ||||||
| 151 | | 参数项 | 描述 | | 170 | | 参数项 | 描述 | | ||||
| 152 | | -- | -- | | 171 | | -- | -- | | ||||
| 153 | -| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 条件变量指针。 | | 172 | +| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 指向条件变量的指针。 | | ||||
| 154 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | mutex指针。 | | 173 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | 指向mutex的指针。 | | ||||
| 155 | -| const struct timespec* time_point | 最大等待到的时间点，超过这个时间点等待返回。 | | 174 | +| const struct timespec* time_point | 等待到期的绝对时间点。 | | ||||
| 156 | 175 | ||||||
| 157 | **返回：** | 176 | **返回：** | ||||
| 158 | 177 | ||||||
| 159 | | 类型 | 说明 | | 178 | | 类型 | 说明 | | ||||
| 160 | | -- | -- | | 179 | | -- | -- | | ||||
| 161 | -| FFRT_C_API int | 等待后被成功唤醒返回ffrt_success，<br> 等待超时返回ffrt_error_timedout，<br> 等待失败ffrt_error_inval。 | | 180 | +| FFRT_C_API int | 阻塞后被成功唤醒时返回`ffrt_success`；<br> 未被唤醒且到达`time_point`时返回`ffrt_error_timedout`；<br> `cond`、`mutex`或`time_point`任一为null时返回`ffrt_error_inval`。 | | ||||
| 181 | + | ||||||
| 182 | +**参考：** | ||||||
| 183 | + | ||||||
| 184 | +[ffrt_cond_wait](capi-condition-variable-h.md#ffrt_cond_wait) | ||||||
| 185 | + | ||||||
| 186 | +[ffrt_cond_signal](capi-condition-variable-h.md#ffrt_cond_signal) | ||||||
| 187 | + | ||||||
| 188 | +[ffrt_cond_broadcast](capi-condition-variable-h.md#ffrt_cond_broadcast) | ||||||
| 189 | + | ||||||
| 162 | 190 | ||||||
| 163 | ### ffrt_cond_destroy() | 191 | ### ffrt_cond_destroy() | ||||
| 164 | 192 | ||||||
| @@ -168,7 +196,7 @@ FFRT_C_API int ffrt_cond_destroy(ffrt_cond_t* cond) | |||||||
| 168 | 196 | ||||||
| 169 | **描述** | 197 | **描述** | ||||
| 170 | 198 | ||||||
| 171 | -销毁条件变量。 | 199 | +销毁条件变量。该条件变量必须已通过[ffrt_cond_init](capi-condition-variable-h.md#ffrt_cond_init)初始化，且在调用本接口时不得被任何线程引用。 | ||||
| 172 | 200 | ||||||
| 173 | **起始版本：** 10 | 201 | **起始版本：** 10 | ||||
| 174 | 202 | ||||||
| @@ -176,12 +204,12 @@ FFRT_C_API int ffrt_cond_destroy(ffrt_cond_t* cond) | |||||||
| 176 | 204 | ||||||
| 177 | | 参数项 | 描述 | | 205 | | 参数项 | 描述 | | ||||
| 178 | | -- | -- | | 206 | | -- | -- | | ||||
| 179 | -| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 条件变量指针。 | | 207 | +| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md)* cond | 指向条件变量的指针。 | | ||||
| 180 | 208 | ||||||
| 181 | **返回：** | 209 | **返回：** | ||||
| 182 | 210 | ||||||
| 183 | | 类型 | 说明 | | 211 | | 类型 | 说明 | | ||||
| 184 | | -- | -- | | 212 | | -- | -- | | ||||
| 185 | -| FFRT_C_API int | 销毁条件变量成功返回ffrt_success，<br>销毁条件变量失败返回ffrt_error_inval。 | | 213 | +| FFRT_C_API int | 条件变量销毁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | | ||||
| 186 | 214 | ||||||
| 187 | 215 | ||||||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_cond_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -FFRT条件变量结构。 | 16 | +条件变量结构体，用于存储条件变量的内部数据。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -27,5 +27,4 @@ FFRT条件变量结构。 | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| uint32_t storage[(ffrt_cond_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | FFRT条件变量占用空间 | | 30 | +| uint32_t storage[(ffrt_cond_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | 条件变量的内部存储。请勿直接访问，通过`ffrt_cond_*`等接口管理。 | |
| 31 | - | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_condattr_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -FFRT条件变量属性结构。 | 16 | +条件变量属性结构体，用于存储条件变量的属性信息。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -27,6 +27,6 @@ FFRT条件变量属性结构。 | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| long storage | FFRT条件变量属性占用空间 | | 30 | +| long storage | 条件变量属性的内部存储。请勿直接访问。 | |
| 31 | 31 | ||
| 32 | 32 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_dependence_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -依赖数据结构。 | 16 | +依赖数据项结构，用于描述任务间的单个依赖关系。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -27,7 +27,7 @@ typedef struct {...} ffrt_dependence_t | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [ffrt_dependence_type_t](capi-type-def-h.md#ffrt_dependence_type_t) type | 依赖类型 | | 30 | +| [ffrt_dependence_type_t](capi-type-def-h.md#ffrt_dependence_type_t) type | 依赖类型。 | |
| 31 | -| const void* ptr | 依赖数据地址 | | 31 | +| const void* ptr | 依赖指针。数据依赖时指向数据，任务依赖时指向任务句柄。 | |
| 32 | 32 | ||
| 33 | 33 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_deps_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -依赖结构定义。 | 16 | +依赖结构体，用于保存任务的依赖列表。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -27,7 +27,7 @@ typedef struct {...} ffrt_deps_t | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| uint32_t len | 依赖数量 | | 30 | +| uint32_t len | 依赖数量。 | |
| 31 | -| const [ffrt_dependence_t*](capi-ffrt-ffrt-dependence-t.md) items | 依赖数据 | | 31 | +| const [ffrt_dependence_t*](capi-ffrt-ffrt-dependence-t.md) items | 依赖数据数组。 | |
| 32 | 32 | ||
| 33 | 33 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_fiber_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -纤程结构。 | 16 | +纤程结构体，用于存储纤程执行上下文。 |
| 17 | 17 | ||
| 18 | **起始版本：** 20 | 18 | **起始版本：** 20 |
| 19 | 19 | ||
| @@ -27,6 +27,6 @@ typedef struct {...} ffrt_fiber_t | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| uintptr_t storage[ffrt_fiber_storage_size] | 纤程上下文占用空间。 | | 30 | +| uintptr_t storage[ffrt_fiber_storage_size] | 纤程执行上下文的内部存储。请勿直接访问，通过[ffrt_fiber_init](capi-fiber-h.md#ffrt_fiber_init)初始化，通过[ffrt_fiber_switch](capi-fiber-h.md#ffrt_fiber_switch)切换。 | |
| 31 | 31 | ||
| 32 | 32 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_function_header_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -任务执行体。 | 16 | +任务执行体，用于定义任务的执行和销毁回调。`exec`回调在任务被调度时调用，`destroy`回调在任务完成后被调用以释放任务相关资源。两者共同管理FFRT任务的完整生命周期。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -27,8 +27,8 @@ typedef struct {...} ffrt_function_header_t | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) exec | 任务执行函数 | | 30 | +| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) exec | 执行任务的函数。在任务被调度时由框架调用。 | |
| 31 | -| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) destroy | 任务销毁函数 | | 31 | +| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) destroy | 销毁任务的函数。在任务执行完毕后由框架调用以释放资源。 | |
| 32 | -| uint64_t reserve[2] | 保留位需要设置为0 | | 32 | +| uint64_t reserve[2] | 保留字段。需设置为0。 | |
| 33 | 33 | ||
| 34 | 34 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_mutex_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -FFRT互斥锁结构。 | 16 | +互斥锁结构体，用于存储互斥锁的内部数据。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -27,6 +27,4 @@ FFRT互斥锁结构。 | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| uint32_t storage[(ffrt_mutex_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | FFRT互斥锁占用空间 | | 30 | +| uint32_t storage[(ffrt_mutex_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | 互斥锁的内部存储。请勿直接访问，通过`ffrt_mutex_*`等接口管理。 | |
| 31 | - | ||
| 32 | - | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_mutexattr_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -FFRT锁属性结构。 | 16 | +互斥锁属性结构体，用于存储互斥锁的属性信息。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -27,6 +27,6 @@ FFRT锁属性结构。 | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| long storage | FFRT锁属性占用空间 | | 30 | +| long storage | 互斥锁属性的内部存储。请勿直接访问，通过[ffrt_mutexattr_init](capi-mutex-h.md#ffrt_mutexattr_init)初始化。 | |
| 31 | 31 | ||
| 32 | 32 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_queue_attr_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -串行队列属性结构。 | 16 | +队列属性结构体，用于存储队列的属性信息。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -23,10 +23,8 @@ typedef struct {...} ffrt_queue_attr_t | |||
| 23 | 23 | ||
| 24 | ## 汇总 | 24 | ## 汇总 |
| 25 | 25 | ||
| 26 | -### 成员变量 | 26 | +### 成员变量 |
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| uint32_t storage[(ffrt_queue_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | 串行队列属性占用空间 | | 30 | +| uint32_t storage[(ffrt_queue_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | 队列属性的内部存储。请勿直接访问，通过[ffrt_queue_attr_init](capi-queue-h.md#ffrt_queue_attr_init)和`ffrt_queue_attr_set_*`等接口管理内容。 | |
| 31 | - | ||
| 32 | - | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_rwlock_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -FFRT读写锁结构。 | 16 | +读写锁结构体，用于存储读写锁的内部数据。 |
| 17 | 17 | ||
| 18 | **起始版本：** 18 | 18 | **起始版本：** 18 |
| 19 | 19 | ||
| @@ -23,9 +23,8 @@ FFRT读写锁结构。 | |||
| 23 | 23 | ||
| 24 | ## 汇总 | 24 | ## 汇总 |
| 25 | 25 | ||
| 26 | -### 成员变量 | 26 | +### 成员变量 |
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| uint32_t storage[(ffrt_rwlock_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | FFRT读写锁占用空间 | | 30 | +| uint32_t storage[(ffrt_rwlock_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | 读写锁的内部存储。请勿直接访问，通过`ffrt_rwlock_*`等接口管理。 | |
| 31 | - | ||
| @@ -2,19 +2,18 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | - | ||
| 11 | ```c | 10 | ```c |
| 12 | typedef struct {...} ffrt_rwlockattr_t | 11 | typedef struct {...} ffrt_rwlockattr_t |
| 13 | ``` | 12 | ``` |
| 14 | 13 | ||
| 15 | ## 概述 | 14 | ## 概述 |
| 16 | 15 | ||
| 17 | -FFRT读写锁属性结构。 | 16 | +读写锁属性结构体，用于存储读写锁的属性信息。 |
| 18 | 17 | ||
| 19 | **起始版本：** 18 | 18 | **起始版本：** 18 |
| 20 | 19 | ||
| @@ -28,6 +27,6 @@ FFRT读写锁属性结构。 | |||
| 28 | 27 | ||
| 29 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 30 | | -- | -- | | 29 | | -- | -- | |
| 31 | -| long storage | FFRT读写锁属性占用空间 | | 30 | +| long storage | 读写锁属性的内部存储。请勿直接访问，直接访问可能导致读写锁属性失效。 | |
| 32 | 31 | ||
| 33 | 32 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -13,7 +13,7 @@ typedef struct {...} ffrt_task_attr_t | |||
| 13 | 13 | ||
| 14 | ## 概述 | 14 | ## 概述 |
| 15 | 15 | ||
| 16 | -并行任务属性结构。 | 16 | +任务属性结构体，用于存储任务的属性信息。 |
| 17 | 17 | ||
| 18 | **起始版本：** 10 | 18 | **起始版本：** 10 |
| 19 | 19 | ||
| @@ -23,10 +23,8 @@ typedef struct {...} ffrt_task_attr_t | |||
| 23 | 23 | ||
| 24 | ## 汇总 | 24 | ## 汇总 |
| 25 | 25 | ||
| 26 | -### 成员变量 | 26 | +### 成员变量 |
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| uint32_t storage[(ffrt_task_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | 任务属性占用空间 | | 30 | +| uint32_t storage[(ffrt_task_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)] | 任务属性的内部存储。请勿直接访问，通过[ffrt_task_attr_init](capi-task-h.md#ffrt_task_attr_init)和`ffrt_task_attr_set_*`等接口管理内容。 | |
| 31 | - | ||
| 32 | - | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ```c | 10 | ```c |
| @@ -2,14 +2,14 @@ | |||||||
| 2 | 2 | ||||||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> | ||||
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> | ||||
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> | ||||
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> | ||||
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> | ||||
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> | ||||
| 9 | 9 | ||||||
| 10 | ## 概述 | 10 | ## 概述 | ||||
| 11 | 11 | ||||||
| 12 | -FFRT（Function Flow运行时）是支持Function Flow编程模型的软件运行时库，用于调度执行开发者基于Function Flow编程模型开发的应用。 | 12 | +提供Function Flow Runtime（FFRT）C接口。FFRT是一种基于任务的并发运行时库，根据任务依赖关系自动调度任务，开发者无需手动管理线程。 | ||||
| 13 | 13 | ||||||
| 14 | **起始版本：** 10 | 14 | **起始版本：** 10 | ||||
| 15 | ## 文件汇总 | 15 | ## 文件汇总 | ||||
| @@ -17,12 +17,12 @@ FFRT（Function Flow运行时）是支持Function Flow编程模型的软件运 | |||||||
| 17 | | 名称 | 描述 | | 17 | | 名称 | 描述 | | ||||
| 18 | | -- | -- | | 18 | | -- | -- | | ||||
| 19 | | [condition_variable.h](capi-condition-variable-h.md) | 声明条件变量的C接口。 | | 19 | | [condition_variable.h](capi-condition-variable-h.md) | 声明条件变量的C接口。 | | ||||
| 20 | -| [fiber.h](capi-fiber-h.md) | 纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换，此为声明纤程的C接口。 | | 20 | +| [fiber.h](capi-fiber-h.md) | 声明纤程的C接口。<br>纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换。 | | ||||
A ❌疑似检测出标点符号问题 错误原因：英文右括号后面跟了空格，在中文文档中应该使用中文右括号 建议修改为： 改动建议
| |||||||
| 21 | -| [loop.h](capi-loop-h.md) | 声明循环的C接口。 | | 21 | +| [loop.h](capi-loop-h.md) | 声明事件循环的C接口。 | | ||||
| 22 | -| [mutex.h](capi-mutex-h.md) | 声明mutex的C接口。 | | 22 | +| [mutex.h](capi-mutex-h.md) | 声明互斥锁（mutex）的C接口，用于在并发任务间提供互斥访问，保护共享资源免受竞争条件影响。 | | ||||
| 23 | | [queue.h](capi-queue-h.md) | 声明队列的C接口。 | | 23 | | [queue.h](capi-queue-h.md) | 声明队列的C接口。 | | ||||
| 24 | -| [shared_mutex.h](capi-shared-mutex-h.md) | 声明rwlock的C接口。 | | 24 | +| [shared_mutex.h](capi-shared-mutex-h.md) | 声明读写锁（rwlock）的C接口。 | | ||||
| 25 | -| [sleep.h](capi-sleep-h.md) | 声明sleep和yield的C接口。 | | 25 | +| [sleep.h](capi-sleep-h.md) | 声明[ffrt_usleep](capi-sleep-h.md#ffrt_usleep)和[ffrt_yield](capi-sleep-h.md#ffrt_yield)的C接口。 | | ||||
| 26 | -| [task.h](capi-task-h.md) | 声明任务的C接口。 | | 26 | +| [task.h](capi-task-h.md) | 声明FFRT任务的C接口，提供任务属性的初始化与销毁、任务QoS设置与获取、任务延迟时间管理、并发队列任务优先级管理、任务栈大小管理、任务提交调度执行、任务句柄引用计数管理以及任务等待等功能。 | | ||||
| 27 | -| [timer.h](capi-timer-h.md) | 声明定时器的C接口。 | | 27 | +| [timer.h](capi-timer-h.md) | 声明定时器的C接口。<br>提供基于QoS等级的定时器能力，支持在指定超时时间后执行回调函数，可用于延时任务调度等场景。 | | ||||
| 28 | | [type_def.h](capi-type-def-h.md) | 定义通用类型。 | | 28 | | [type_def.h](capi-type-def-h.md) | 定义通用类型。 | | ||||
| @@ -2,14 +2,14 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| 11 | 11 | ||
| 12 | -纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换，此为声明纤程的C接口。 | 12 | +声明纤程的C接口。纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换。 |
| 13 | 13 | ||
| 14 | **引用文件：** <ffrt/fiber.h> | 14 | **引用文件：** <ffrt/fiber.h> |
| 15 | 15 | ||
| @@ -27,8 +27,8 @@ | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(\*func)(void*), void* arg, void* stack, size_t stack_size)](#ffrt_fiber_init) | 纤程初始化函数，此函数初始化纤程实例，该实例可以存储上下文。 | | 30 | +| [FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(\*func)(void*), void* arg, void* stack, size_t stack_size)](#ffrt_fiber_init) | 初始化纤程。初始化纤程结构，使其准备好被执行。调用者需负责分配`stack`指向的栈内存，并保证该内存在纤程整个生命周期内有效。 | |
| 31 | -| [FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to)](#ffrt_fiber_switch) | 纤程切换函数，调用该函数的线程会暂停当前任务的执行，并将当前上下文保存到from纤程中，同时恢复to纤程中的上下文。 | | 31 | +| [FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to)](#ffrt_fiber_switch) | 在两个纤程间切换执行上下文。将当前执行上下文保存到`from`指定的纤程中，并从`to`指定的纤程恢复执行上下文。`from`和`to`都必须指向已通过[ffrt_fiber_init](capi-fiber-h.md#ffrt_fiber_init)初始化的纤程实例；否则行为未定义。 | |
| 32 | 32 | ||
| 33 | ## 函数说明 | 33 | ## 函数说明 |
| 34 | 34 | ||
| @@ -40,7 +40,7 @@ FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* ar | |||
| 40 | 40 | ||
| 41 | **描述** | 41 | **描述** |
| 42 | 42 | ||
| 43 | -纤程初始化函数，此函数初始化纤程实例，该实例可以存储上下文。 | 43 | +初始化纤程。初始化纤程结构，使其准备好被执行。调用者需负责分配`stack`指向的栈内存，并保证该内存在纤程整个生命周期内有效。 |
| 44 | 44 | ||
| 45 | **起始版本：** 20 | 45 | **起始版本：** 20 |
| 46 | 46 | ||
| @@ -48,17 +48,17 @@ FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* ar | |||
| 48 | 48 | ||
| 49 | | 参数项 | 描述 | | 49 | | 参数项 | 描述 | |
| 50 | | -- | -- | | 50 | | -- | -- | |
| 51 | -| fiber | 指向要初始化的纤程的指针，具体可参考[ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md)。 | | 51 | +| [ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md)\* fiber | 指向待初始化的纤程结构的指针。 | |
| 52 | -| func | 纤程切换后所要执行的方法。 | | 52 | +| void(\*func)(void\*) | 纤程将执行的入口函数。 | |
| 53 | -| void\* arg | 纤程切换后所要执行方法的入参。 | | 53 | +| void\* arg | 传递给入口函数的参数。 | |
| 54 | -| void\* stack | 纤程堆栈内存指针。 | | 54 | +| void\* stack | 指向纤程栈所用内存区域的指针。 | |
| 55 | -| size_t stack_size | 纤程堆栈大小，具体可参考[ffrt_storage_size_t](capi-type-def-h.md#ffrt_storage_size_t)。 | | 55 | +| size_t stack_size | 栈的大小，单位是字节。必须足以容纳纤程上下文。 | |
| 56 | 56 | ||
| 57 | **返回：** | 57 | **返回：** |
| 58 | 58 | ||
| 59 | | 类型 | 说明 | | 59 | | 类型 | 说明 | |
| 60 | | -- | -- | | 60 | | -- | -- | |
| 61 | -| FFRT_C_API int | 初始化成功返回ffrt_success，否则返回ffrt_error。 | | 61 | +| FFRT_C_API int | 纤程初始化成功时返回`ffrt_success`；<br> `stack_size`过小（不足以容纳纤程上下文）时返回`ffrt_error_inval`。 | |
| 62 | 62 | ||
| 63 | ### ffrt_fiber_switch() | 63 | ### ffrt_fiber_switch() |
| 64 | 64 | ||
| @@ -68,7 +68,7 @@ FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to) | |||
| 68 | 68 | ||
| 69 | **描述** | 69 | **描述** |
| 70 | 70 | ||
| 71 | -纤程切换函数，调用该函数的线程会暂停当前任务的执行，并将当前上下文保存到from纤程中，同时恢复to纤程中的上下文。 | 71 | +在两个纤程间切换执行上下文。将当前执行上下文保存到`from`指定的纤程中，并从`to`指定的纤程恢复执行上下文。`from`和`to`都必须指向已通过[ffrt_fiber_init](capi-fiber-h.md#ffrt_fiber_init)初始化的纤程实例；否则行为未定义。 |
| 72 | 72 | ||
| 73 | **起始版本：** 20 | 73 | **起始版本：** 20 |
| 74 | 74 | ||
| @@ -76,7 +76,12 @@ FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to) | |||
| 76 | 76 | ||
| 77 | | 参数项 | 描述 | | 77 | | 参数项 | 描述 | |
| 78 | | -- | -- | | 78 | | -- | -- | |
| 79 | -| [ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md)* from | 将要保存的纤程指针。 | | 79 | +| [ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md)* from | 指向用于保存当前上下文的纤程的指针。 | |
| 80 | -| [ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md)* to | 将要恢复的纤程指针。 | | 80 | +| [ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md)* to | 指向用于恢复执行上下文的纤程的指针。 | |
| 81 | + | ||
| 82 | +**参考：** | ||
| 83 | + | ||
| 84 | +[ffrt_fiber_init](capi-fiber-h.md#ffrt_fiber_init) | ||
| 85 | + | ||
| 81 | 86 | ||
| 82 | 87 | ||
| @@ -2,14 +2,14 @@ | |||||||
| 2 | 2 | ||||||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> | ||||
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> | ||||
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> | ||||
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> | ||||
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> | ||||
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> | ||||
| 9 | 9 | ||||||
| 10 | ## 概述 | 10 | ## 概述 | ||||
| 11 | 11 | ||||||
| 12 | -声明循环的C接口。 | 12 | +声明事件循环的C接口。 | ||||
| 13 | 13 | ||||||
| 14 | **引用文件：** <ffrt/loop.h> | 14 | **引用文件：** <ffrt/loop.h> | ||||
| 15 | 15 | ||||||
| @@ -27,20 +27,19 @@ | |||||||
| 27 | 27 | ||||||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | | ||||
| 29 | |-----------------|----| | 29 | |-----------------|----| | ||||
| 30 | -| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) | loop句柄。 | | 30 | +| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) | loop句柄，用于标识不同的loop。 | | ||||
| 31 | - | ||||||
| 32 | 31 | ||||||
| 33 | ### 函数 | 32 | ### 函数 | ||||
| 34 | 33 | ||||||
| 35 | | 名称 | 描述 | | 34 | | 名称 | 描述 | | ||||
| 36 | | -- | -- | | 35 | | -- | -- | | ||||
| 37 | -| [FFRT_C_API ffrt_loop_t ffrt_loop_create(ffrt_queue_t queue)](#ffrt_loop_create) | 创建loop对象。 | | 36 | +| [FFRT_C_API ffrt_loop_t ffrt_loop_create(ffrt_queue_t queue)](#ffrt_loop_create) | 在指定的队列上创建loop，用于运行事件循环。 | | ||||
| 38 | -| [FFRT_C_API int ffrt_loop_destroy(ffrt_loop_t loop)](#ffrt_loop_destroy) | 销毁loop对象。 | | 37 | +| [FFRT_C_API int ffrt_loop_destroy(ffrt_loop_t loop)](#ffrt_loop_destroy) | 销毁loop。调用该接口可释放与loop关联的资源。 | | ||||
| 39 | -| [FFRT_C_API int ffrt_loop_run(ffrt_loop_t loop)](#ffrt_loop_run) | 开启loop循环。 | | 38 | +| [FFRT_C_API int ffrt_loop_run(ffrt_loop_t loop)](#ffrt_loop_run) | 启动一次loop循环。该函数会独占调用线程，在当前调用线程中同步运行事件循环，直到调用[ffrt_loop_stop](capi-loop-h.md#ffrt_loop_stop)后才会返回。 | | ||||
| 40 | -| [FFRT_C_API void ffrt_loop_stop(ffrt_loop_t loop)](#ffrt_loop_stop) | 停止loop循环。 | | 39 | +| [FFRT_C_API void ffrt_loop_stop(ffrt_loop_t loop)](#ffrt_loop_stop) | 停止loop循环。调用后，正在执行[ffrt_loop_run](capi-loop-h.md#ffrt_loop_run)的线程将停止循环并返回。 | | ||||
| 41 | -| [FFRT_C_API int ffrt_loop_epoll_ctl(ffrt_loop_t loop, int op, int fd, uint32_t events, void *data, ffrt_poller_cb cb)](#ffrt_loop_epoll_ctl) | 管理loop上的监听事件。<br> 不建议在`cb`中调用`exit`函数，可能导致未定义行为。 | | 40 | +| [FFRT_C_API int ffrt_loop_epoll_ctl(ffrt_loop_t loop, int op, int fd, uint32_t events, void *data, ffrt_poller_cb cb)](#ffrt_loop_epoll_ctl) | 在ffrt loop上控制epoll文件描述符。在目标文件描述符上添加、修改或删除监听的事件。 | | ||||
A ❌疑似检测出中文错别字问题 错误原因："的"应该改为"得"，表示程度或结果 建议修改为： 改动建议
| |||||||
| 42 | -| [FFRT_C_API ffrt_timer_t ffrt_loop_timer_start(ffrt_loop_t loop, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat)](#ffrt_loop_timer_start) | 在ffrt loop上启动定时器。<br> 不建议在`cb`中调用`exit`函数，可能导致未定义行为。 | | 41 | +| [FFRT_C_API ffrt_timer_t ffrt_loop_timer_start(ffrt_loop_t loop, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat)](#ffrt_loop_timer_start) | 在ffrt loop上启动定时器。超时后调用回调函数；若`repeat`为`true`，则周期性重复触发。 | | ||||
| 43 | -| [FFRT_C_API int ffrt_loop_timer_stop(ffrt_loop_t loop, ffrt_timer_t handle)](#ffrt_loop_timer_stop) | 停止ffrt loop定时器。 | | 42 | +| [FFRT_C_API int ffrt_loop_timer_stop(ffrt_loop_t loop, ffrt_timer_t handle)](#ffrt_loop_timer_stop) | 在ffrt loop上停止定时器。调用后，该定时器不再触发。 | | ||||
| 44 | 43 | ||||||
| 45 | ## 函数说明 | 44 | ## 函数说明 | ||||
| 46 | 45 | ||||||
| @@ -52,21 +51,21 @@ FFRT_C_API ffrt_loop_t ffrt_loop_create(ffrt_queue_t queue) | |||||||
| 52 | 51 | ||||||
| 53 | **描述** | 52 | **描述** | ||||
| 54 | 53 | ||||||
| 55 | -创建loop对象。 | 54 | +在指定的队列上创建loop，用于运行事件循环。 | ||||
| 56 | 55 | ||||||
| 57 | **起始版本：** 12 | 56 | **起始版本：** 12 | ||||
| 58 | 57 | ||||||
| 59 | **参数：** | 58 | **参数：** | ||||
| 60 | 59 | ||||||
| 61 | -| 参数项 | 描述 | | 60 | +| 参数项 | 描述 | | ||||
| 62 | -|------------------------| -- | | 61 | +| -- | -- | | ||||
| 63 | -| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 并发队列。 | | 62 | +| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列。 | | ||||
| 64 | 63 | ||||||
| 65 | **返回：** | 64 | **返回：** | ||||
| 66 | 65 | ||||||
| 67 | -| 类型 | 说明 | | 66 | +| 类型 | 说明 | | ||||
| 68 | -|----------------------------| -- | | 67 | +| -- | -- | | ||||
| 69 | -| FFRT_C_API [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) | 创建成功返回ffrt_loop_t对象，<br> 创建失败返回空指针。 | | 68 | +| FFRT_C_API [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) | loop创建成功时返回非空的loop句柄；<br> 否则返回空指针。 | | ||||
| 70 | 69 | ||||||
| 71 | ### ffrt_loop_destroy() | 70 | ### ffrt_loop_destroy() | ||||
| 72 | 71 | ||||||
| @@ -76,7 +75,7 @@ FFRT_C_API int ffrt_loop_destroy(ffrt_loop_t loop) | |||||||
| 76 | 75 | ||||||
| 77 | **描述** | 76 | **描述** | ||||
| 78 | 77 | ||||||
| 79 | -销毁loop对象。 | 78 | +销毁loop。调用该接口可释放与loop关联的资源。 | ||||
| 80 | 79 | ||||||
| 81 | **起始版本：** 12 | 80 | **起始版本：** 12 | ||||
| 82 | 81 | ||||||
| @@ -84,13 +83,13 @@ FFRT_C_API int ffrt_loop_destroy(ffrt_loop_t loop) | |||||||
| 84 | 83 | ||||||
| 85 | | 参数项 | 描述 | | 84 | | 参数项 | 描述 | | ||||
| 86 | | -- | -- | | 85 | | -- | -- | | ||||
| 87 | -| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop对象。 | | 86 | +| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop句柄。 | | ||||
| 88 | 87 | ||||||
| 89 | **返回：** | 88 | **返回：** | ||||
| 90 | 89 | ||||||
| 91 | | 类型 | 说明 | | 90 | | 类型 | 说明 | | ||||
| 92 | | -- | -- | | 91 | | -- | -- | | ||||
| 93 | -| FFRT_C_API int | 销毁成功返回0，<br> 销毁失败返回-1。 | | 92 | +| FFRT_C_API int | loop销毁成功时返回`0`；<br> 否则返回`-1`。 | | ||||
| 94 | 93 | ||||||
| 95 | ### ffrt_loop_run() | 94 | ### ffrt_loop_run() | ||||
| 96 | 95 | ||||||
| @@ -100,7 +99,7 @@ FFRT_C_API int ffrt_loop_run(ffrt_loop_t loop) | |||||||
| 100 | 99 | ||||||
| 101 | **描述** | 100 | **描述** | ||||
| 102 | 101 | ||||||
| 103 | -开启loop循环。 | 102 | +启动一次loop循环。该函数会独占调用线程，在当前调用线程中同步运行事件循环，直到调用[ffrt_loop_stop](capi-loop-h.md#ffrt_loop_stop)后才会返回。 | ||||
| 104 | 103 | ||||||
| 105 | **起始版本：** 12 | 104 | **起始版本：** 12 | ||||
| 106 | 105 | ||||||
| @@ -108,13 +107,18 @@ FFRT_C_API int ffrt_loop_run(ffrt_loop_t loop) | |||||||
| 108 | 107 | ||||||
| 109 | | 参数项 | 描述 | | 108 | | 参数项 | 描述 | | ||||
| 110 | | -- | -- | | 109 | | -- | -- | | ||||
| 111 | -| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop对象。 | | 110 | +| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop句柄。 | | ||||
| 112 | 111 | ||||||
| 113 | **返回：** | 112 | **返回：** | ||||
| 114 | 113 | ||||||
| 115 | | 类型 | 说明 | | 114 | | 类型 | 说明 | | ||||
| 116 | | -- | -- | | 115 | | -- | -- | | ||||
| 117 | -| FFRT_C_API int | loop循环失败返回-1，<br> loop循环成功返回0。 | | 116 | +| FFRT_C_API int | loop运行成功时返回`0`；<br> 否则返回`-1`。 | | ||||
| 117 | + | ||||||
| 118 | +**参考：** | ||||||
| 119 | + | ||||||
| 120 | +[ffrt_loop_stop](capi-loop-h.md#ffrt_loop_stop) | ||||||
| 121 | + | ||||||
| 118 | 122 | ||||||
| 119 | ### ffrt_loop_stop() | 123 | ### ffrt_loop_stop() | ||||
| 120 | 124 | ||||||
| @@ -124,7 +128,7 @@ FFRT_C_API void ffrt_loop_stop(ffrt_loop_t loop) | |||||||
| 124 | 128 | ||||||
| 125 | **描述** | 129 | **描述** | ||||
| 126 | 130 | ||||||
| 127 | -停止loop循环。 | 131 | +停止loop循环。调用后，正在执行[ffrt_loop_run](capi-loop-h.md#ffrt_loop_run)的线程将停止循环并返回。 | ||||
| 128 | 132 | ||||||
| 129 | **起始版本：** 12 | 133 | **起始版本：** 12 | ||||
| 130 | 134 | ||||||
| @@ -132,7 +136,12 @@ FFRT_C_API void ffrt_loop_stop(ffrt_loop_t loop) | |||||||
| 132 | 136 | ||||||
| 133 | | 参数项 | 描述 | | 137 | | 参数项 | 描述 | | ||||
| 134 | | -- | -- | | 138 | | -- | -- | | ||||
| 135 | -| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop对象。 | | 139 | +| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop句柄。 | | ||||
| 140 | + | ||||||
| 141 | +**参考：** | ||||||
| 142 | + | ||||||
| 143 | +[ffrt_loop_run](capi-loop-h.md#ffrt_loop_run) | ||||||
| 144 | + | ||||||
| 136 | 145 | ||||||
| 137 | ### ffrt_loop_epoll_ctl() | 146 | ### ffrt_loop_epoll_ctl() | ||||
| 138 | 147 | ||||||
| @@ -142,9 +151,7 @@ FFRT_C_API int ffrt_loop_epoll_ctl(ffrt_loop_t loop, int op, int fd, uint32_t ev | |||||||
| 142 | 151 | ||||||
| 143 | **描述** | 152 | **描述** | ||||
| 144 | 153 | ||||||
| 145 | -管理loop上的监听事件。 | 154 | +在ffrt loop上控制epoll文件描述符。在目标文件描述符上添加、修改或删除监听的事件。 | ||||
A ❌疑似检测出中文错别字问题 错误原因："的"应该改为"得"，表示程度或结果 建议修改为： 改动建议
| |||||||
| 146 | - | ||||||
| 147 | -不建议在`cb`中调用`exit`函数，可能导致未定义行为。 | ||||||
| 148 | 155 | ||||||
| 149 | **起始版本：** 12 | 156 | **起始版本：** 12 | ||||
| 150 | 157 | ||||||
| @@ -152,18 +159,18 @@ FFRT_C_API int ffrt_loop_epoll_ctl(ffrt_loop_t loop, int op, int fd, uint32_t ev | |||||||
| 152 | 159 | ||||||
| 153 | | 参数项 | 描述 | | 160 | | 参数项 | 描述 | | ||||
| 154 | | -- | -- | | 161 | | -- | -- | | ||||
| 155 | -| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop对象。 | | 162 | +| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop句柄。 | | ||||
| 156 | -| int op | fd操作符。 | | 163 | +| int op | 在目标文件描述符上执行的操作类型，如添加、修改或删除。 | | ||||
| 157 | -| int fd | 事件描述符。 | | 164 | +| int fd | 执行操作的目标文件描述符。 | | ||||
| 158 | -| uint32_t events | 事件。 | | 165 | +| uint32_t events | 监听的事件类型（如可读、可写等），支持按位或组合。 | | ||||
A ❌疑似检测出中文错别字问题 错误原因："的"应该改为"得"，表示程度或结果 建议修改为： 改动建议
| |||||||
| 159 | -| void *data | 事件变化时触发的回调函数的入参。 | | 166 | +| void *data | 传递给`cb`的用户数据。 | | ||||
| 160 | -| [ffrt_poller_cb](capi-type-def-h.md#ffrt_poller_cb) cb | 事件变化时触发的回调函数。 | | 167 | +| [ffrt_poller_cb](capi-type-def-h.md#ffrt_poller_cb) cb | 当目标fd被轮询到时执行的用户回调函数。 | | ||||
| 161 | 168 | ||||||
| 162 | **返回：** | 169 | **返回：** | ||||
| 163 | 170 | ||||||
| 164 | | 类型 | 说明 | | 171 | | 类型 | 说明 | | ||||
| 165 | | -- | -- | | 172 | | -- | -- | | ||||
| 166 | -| FFRT_C_API int | 成功返回0，<br> 失败返回-1。 | | 173 | +| FFRT_C_API int | 操作成功时返回`0`；<br> 否则返回`-1`。 | | ||||
| 167 | 174 | ||||||
| 168 | ### ffrt_loop_timer_start() | 175 | ### ffrt_loop_timer_start() | ||||
| 169 | 176 | ||||||
| @@ -173,9 +180,7 @@ FFRT_C_API ffrt_timer_t ffrt_loop_timer_start(ffrt_loop_t loop, uint64_t timeout | |||||||
| 173 | 180 | ||||||
| 174 | **描述** | 181 | **描述** | ||||
| 175 | 182 | ||||||
| 176 | -在ffrt loop上启动定时器。 | 183 | +在ffrt loop上启动定时器。超时后调用回调函数；若`repeat`为`true`，则周期性重复触发。 | ||||
| 177 | - | ||||||
| 178 | -不建议在`cb`中调用`exit`函数，可能导致未定义行为。 | ||||||
| 179 | 184 | ||||||
| 180 | **起始版本：** 12 | 185 | **起始版本：** 12 | ||||
| 181 | 186 | ||||||
| @@ -183,17 +188,22 @@ FFRT_C_API ffrt_timer_t ffrt_loop_timer_start(ffrt_loop_t loop, uint64_t timeout | |||||||
| 183 | 188 | ||||||
| 184 | | 参数项 | 描述 | | 189 | | 参数项 | 描述 | | ||||
| 185 | | -- | -- | | 190 | | -- | -- | | ||||
| 186 | -| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop对象。 | | 191 | +| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop句柄。 | | ||||
| 187 | -| uint64_t timeout | 超时时间(毫秒)。 | | 192 | +| uint64_t timeout | 超时时间，单位是毫秒，取值范围为[0, +∞)。 | | ||||
| 188 | -| void* data | 事件变化时触发的回调函数的入参。 | | 193 | +| void* data | 传递给`cb`的用户数据。 | | ||||
| 189 | -| [ffrt_timer_cb](capi-type-def-h.md#ffrt_timer_cb) cb | 事件变化时触发的回调函数。 | | 194 | +| [ffrt_timer_cb](capi-type-def-h.md#ffrt_timer_cb) cb | 超时后执行的用户回调函数。 | | ||||
| 190 | -| bool repeat | 是否重复执行该定时器。 | | 195 | +| bool repeat | 是否重复执行该定时器。`true`表示重复，`false`表示只执行一次。 | | ||||
| 191 | 196 | ||||||
| 192 | **返回：** | 197 | **返回：** | ||||
| 193 | 198 | ||||||
| 194 | | 类型 | 说明 | | 199 | | 类型 | 说明 | | ||||
| 195 | | -- | -- | | 200 | | -- | -- | | ||||
| 196 | -| FFRT_C_API [ffrt_timer_t](capi-type-def-h.md#变量) | 返回定时器句柄。 | | 201 | +| FFRT_C_API [ffrt_timer_t](capi-type-def-h.md#变量) | 定时器句柄；若`loop`或`cb`为空则返回`-1`。 | | ||||
| 202 | + | ||||||
| 203 | +**参考：** | ||||||
| 204 | + | ||||||
| 205 | +[ffrt_loop_timer_stop](capi-loop-h.md#ffrt_loop_timer_stop) | ||||||
| 206 | + | ||||||
| 197 | 207 | ||||||
| 198 | ### ffrt_loop_timer_stop() | 208 | ### ffrt_loop_timer_stop() | ||||
| 199 | 209 | ||||||
| @@ -203,7 +213,7 @@ FFRT_C_API int ffrt_loop_timer_stop(ffrt_loop_t loop, ffrt_timer_t handle) | |||||||
| 203 | 213 | ||||||
| 204 | **描述** | 214 | **描述** | ||||
| 205 | 215 | ||||||
| 206 | -停止ffrt loop定时器。 | 216 | +在ffrt loop上停止定时器。调用后，该定时器不再触发。 | ||||
| 207 | 217 | ||||||
| 208 | **起始版本：** 12 | 218 | **起始版本：** 12 | ||||
| 209 | 219 | ||||||
| @@ -211,13 +221,18 @@ FFRT_C_API int ffrt_loop_timer_stop(ffrt_loop_t loop, ffrt_timer_t handle) | |||||||
| 211 | 221 | ||||||
| 212 | | 参数项 | 描述 | | 222 | | 参数项 | 描述 | | ||||
| 213 | | -- | -- | | 223 | | -- | -- | | ||||
| 214 | -| ffrt_loop_t loop | loop对象。 | | 224 | +| [ffrt_loop_t](capi-ffrt-ffrt-loop-t.md) loop | loop句柄。 | | ||||
| 215 | -| ffrt_timer_t handle | timer对象。 | | 225 | +| [ffrt_timer_t](capi-type-def-h.md#变量) handle | 定时器句柄，由[ffrt_loop_timer_start](capi-loop-h.md#ffrt_loop_timer_start)返回。 | | ||||
| 216 | 226 | ||||||
| 217 | **返回：** | 227 | **返回：** | ||||
| 218 | 228 | ||||||
| 219 | | 类型 | 说明 | | 229 | | 类型 | 说明 | | ||||
| 220 | | -- | -- | | 230 | | -- | -- | | ||||
| 221 | -| FFRT_C_API int | 成功返回0，<br>失败返回-1。 | | 231 | +| FFRT_C_API int | 操作成功时返回`0`；<br> 否则返回`-1`。 | | ||||
| 232 | + | ||||||
| 233 | +**参考：** | ||||||
| 234 | + | ||||||
| 235 | +[ffrt_loop_timer_start](capi-loop-h.md#ffrt_loop_timer_start) | ||||||
| 236 | + | ||||||
| 222 | 237 | ||||||
| 223 | 238 | ||||||
| @@ -2,14 +2,14 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| 11 | 11 | ||
| 12 | -声明mutex的C接口。 | 12 | +声明互斥锁（mutex）的C接口，用于在并发任务间提供互斥访问，保护共享资源免受竞争条件影响。 |
| 13 | 13 | ||
| 14 | **引用文件：** <ffrt/mutex.h> | 14 | **引用文件：** <ffrt/mutex.h> |
| 15 | 15 | ||
| @@ -27,15 +27,15 @@ | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr)](#ffrt_mutexattr_init) | 初始化mutex属性。 | | 30 | +| [FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr)](#ffrt_mutexattr_init) | 初始化mutex属性。初始化成功后，mutex属性被设置为默认值。该mutex属性不再使用时，必须通过[ffrt_mutexattr_destroy](capi-mutex-h.md#ffrt_mutexattr_destroy)销毁。 | |
| 31 | -| [FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type)](#ffrt_mutexattr_settype) | 设置mutex属性类型。 | | 31 | +| [FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type)](#ffrt_mutexattr_settype) | 设置mutex属性的类型。类型可以是`ffrt_mutex_normal`（普通互斥锁）或`ffrt_mutex_recursive`（递归互斥锁，允许同一任务多次获取该锁）。 | |
| 32 | -| [FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type)](#ffrt_mutexattr_gettype) | 获取mutex类型。 | | 32 | +| [FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type)](#ffrt_mutexattr_gettype) | 获取mutex属性的类型。调用成功后，类型值通过出参`type`返回。 | |
| 33 | -| [FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr)](#ffrt_mutexattr_destroy) | 销毁mutex属性，用户需要调用此接口。 | | 33 | +| [FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr)](#ffrt_mutexattr_destroy) | 销毁mutex属性。该mutex属性必须已通过[ffrt_mutexattr_init](capi-mutex-h.md#ffrt_mutexattr_init)初始化。 | |
| 34 | -| [FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr)](#ffrt_mutex_init) | 初始化mutex。 | | 34 | +| [FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr)](#ffrt_mutex_init) | 初始化mutex。该mutex不再使用时，必须通过[ffrt_mutex_destroy](capi-mutex-h.md#ffrt_mutex_destroy)销毁。通过`attr`传入已配置的mutex属性，或传入空指针使用默认值。 | |
| 35 | -| [FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex)](#ffrt_mutex_lock) | 获取mutex。 | | 35 | +| [FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex)](#ffrt_mutex_lock) | 加锁mutex。若mutex已被其他线程持有，则阻塞当前线程直到mutex可用。成功时，调用线程持有该mutex，直至通过[ffrt_mutex_unlock](capi-mutex-h.md#ffrt_mutex_unlock)释放。 | |
| 36 | -| [FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex)](#ffrt_mutex_unlock) | 释放mutex。 | | 36 | +| [FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex)](#ffrt_mutex_unlock) | 解锁mutex。调用线程必须已持有该mutex，且该锁之前由[ffrt_mutex_lock](capi-mutex-h.md#ffrt_mutex_lock)或[ffrt_mutex_trylock](capi-mutex-h.md#ffrt_mutex_trylock)获取。 | |
| 37 | -| [FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex)](#ffrt_mutex_trylock) | 尝试获取mutex。 | | 37 | +| [FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex)](#ffrt_mutex_trylock) | 尝试加锁mutex。该接口为非阻塞操作：若mutex已被其他线程持有，则立即返回错误码。成功时，调用线程持有该mutex，直至通过[ffrt_mutex_unlock](capi-mutex-h.md#ffrt_mutex_unlock)释放。 | |
| 38 | -| [FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex)](#ffrt_mutex_destroy) | 销毁mutex。 | | 38 | +| [FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex)](#ffrt_mutex_destroy) | 销毁mutex。调用成功后，mutex占用的资源被释放，该mutex对象不可再使用。该mutex必须已通过[ffrt_mutex_init](capi-mutex-h.md#ffrt_mutex_init)初始化，且在调用本接口时不得被任何线程持有。 | |
| 39 | 39 | ||
| 40 | ## 函数说明 | 40 | ## 函数说明 |
| 41 | 41 | ||
| @@ -47,7 +47,7 @@ FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr) | |||
| 47 | 47 | ||
| 48 | **描述** | 48 | **描述** |
| 49 | 49 | ||
| 50 | -初始化mutex属性。 | 50 | +初始化mutex属性。初始化成功后，mutex属性被设置为默认值。该mutex属性不再使用时，必须通过[ffrt_mutexattr_destroy](capi-mutex-h.md#ffrt_mutexattr_destroy)销毁。 |
| 51 | 51 | ||
| 52 | **起始版本：** 12 | 52 | **起始版本：** 12 |
| 53 | 53 | ||
| @@ -55,13 +55,13 @@ FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr) | |||
| 55 | 55 | ||
| 56 | | 参数项 | 描述 | | 56 | | 参数项 | 描述 | |
| 57 | | -- | -- | | 57 | | -- | -- | |
| 58 | -| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | mutex属性指针。 | | 58 | +| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | 指向mutex属性的指针。 | |
| 59 | 59 | ||
| 60 | **返回：** | 60 | **返回：** |
| 61 | 61 | ||
| 62 | | 类型 | 说明 | | 62 | | 类型 | 说明 | |
| 63 | | -- | -- | | 63 | | -- | -- | |
| 64 | -| FFRT_C_API int | mutex属性初始化成功返回ffrt_success，<br> mutex属性初始化失败返回ffrt_error_inval。 | | 64 | +| FFRT_C_API int | mutex属性初始化成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 65 | 65 | ||
| 66 | ### ffrt_mutexattr_settype() | 66 | ### ffrt_mutexattr_settype() |
| 67 | 67 | ||
| @@ -71,7 +71,7 @@ FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type) | |||
| 71 | 71 | ||
| 72 | **描述** | 72 | **描述** |
| 73 | 73 | ||
| 74 | -设置mutex属性类型。 | 74 | +设置mutex属性的类型。类型可以是`ffrt_mutex_normal`（普通互斥锁）或`ffrt_mutex_recursive`（递归互斥锁，允许同一任务多次获取该锁）。 |
| 75 | 75 | ||
| 76 | **起始版本：** 12 | 76 | **起始版本：** 12 |
| 77 | 77 | ||
| @@ -79,14 +79,19 @@ FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type) | |||
| 79 | 79 | ||
| 80 | | 参数项 | 描述 | | 80 | | 参数项 | 描述 | |
| 81 | | -- | -- | | 81 | | -- | -- | |
| 82 | -| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | mutex属性指针。 | | 82 | +| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | 指向mutex属性的指针。 | |
| 83 | -| int type | mutex类型。 | | 83 | +| int type | mutex类型，取值为`ffrt_mutex_normal`、`ffrt_mutex_recursive`或`ffrt_mutex_default`（等价于`ffrt_mutex_normal`）。 | |
| 84 | 84 | ||
| 85 | **返回：** | 85 | **返回：** |
| 86 | 86 | ||
| 87 | | 类型 | 说明 | | 87 | | 类型 | 说明 | |
| 88 | | -- | -- | | 88 | | -- | -- | |
| 89 | -| FFRT_C_API int | mutex属性类型设置成功返回ffrt_success，<br> mutex属性指针是空或者<br> mutex类型不是ffrt_mutex_normal或ffrt_mutex_recursive返回ffrt_error_inval。 | | 89 | +| FFRT_C_API int | mutex属性类型设置成功时返回`ffrt_success`；<br> 当attr为空指针，或mutex属性类型既不是`ffrt_mutex_normal`也不是`ffrt_mutex_recursive`时<br> 返回`ffrt_error_inval`。 | |
| 90 | + | ||
| 91 | +**参考：** | ||
| 92 | + | ||
| 93 | +[ffrt_mutex_type](capi-type-def-h.md#ffrt_mutex_type) | ||
| 94 | + | ||
| 90 | 95 | ||
| 91 | ### ffrt_mutexattr_gettype() | 96 | ### ffrt_mutexattr_gettype() |
| 92 | 97 | ||
| @@ -96,7 +101,7 @@ FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type) | |||
| 96 | 101 | ||
| 97 | **描述** | 102 | **描述** |
| 98 | 103 | ||
| 99 | -获取mutex类型。 | 104 | +获取mutex属性的类型。调用成功后，类型值通过出参`type`返回。 |
| 100 | 105 | ||
| 101 | **起始版本：** 12 | 106 | **起始版本：** 12 |
| 102 | 107 | ||
| @@ -104,14 +109,14 @@ FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type) | |||
| 104 | 109 | ||
| 105 | | 参数项 | 描述 | | 110 | | 参数项 | 描述 | |
| 106 | | -- | -- | | 111 | | -- | -- | |
| 107 | -| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | mutex属性指针。 | | 112 | +| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | 指向mutex属性的指针。 | |
| 108 | -| int* type | mutex类型指针。 | | 113 | +| int* type | 指向mutex类型的指针，用于接收获取的类型值（`ffrt_mutex_normal`或`ffrt_mutex_recursive`）。 | |
| 109 | 114 | ||
| 110 | **返回：** | 115 | **返回：** |
| 111 | 116 | ||
| 112 | | 类型 | 说明 | | 117 | | 类型 | 说明 | |
| 113 | | -- | -- | | 118 | | -- | -- | |
| 114 | -| FFRT_C_API int | mutex类型获取成功返回ffrt_success，<br> mutex属性指针或mutex类型指针是空返回ffrt_error_inval。 | | 119 | +| FFRT_C_API int | mutex属性类型获取成功时返回`ffrt_success`；<br> attr或type为空指针时返回`ffrt_error_inval`。 | |
| 115 | 120 | ||
| 116 | ### ffrt_mutexattr_destroy() | 121 | ### ffrt_mutexattr_destroy() |
| 117 | 122 | ||
| @@ -121,7 +126,7 @@ FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr) | |||
| 121 | 126 | ||
| 122 | **描述** | 127 | **描述** |
| 123 | 128 | ||
| 124 | -销毁mutex属性，用户需要调用此接口。 | 129 | +销毁mutex属性。该mutex属性必须已通过[ffrt_mutexattr_init](capi-mutex-h.md#ffrt_mutexattr_init)初始化。 |
| 125 | 130 | ||
| 126 | **起始版本：** 12 | 131 | **起始版本：** 12 |
| 127 | 132 | ||
| @@ -129,13 +134,13 @@ FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr) | |||
| 129 | 134 | ||
| 130 | | 参数项 | 描述 | | 135 | | 参数项 | 描述 | |
| 131 | | -- | -- | | 136 | | -- | -- | |
| 132 | -| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | mutex属性指针。 | | 137 | +| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | 指向mutex属性的指针。 | |
| 133 | 138 | ||
| 134 | **返回：** | 139 | **返回：** |
| 135 | 140 | ||
| 136 | | 类型 | 说明 | | 141 | | 类型 | 说明 | |
| 137 | | -- | -- | | 142 | | -- | -- | |
| 138 | -| FFRT_C_API int | mutex属性销毁成功返回ffrt_success，<br> mutex属性销毁失败返回ffrt_error_inval。 | | 143 | +| FFRT_C_API int | mutex属性销毁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 139 | 144 | ||
| 140 | ### ffrt_mutex_init() | 145 | ### ffrt_mutex_init() |
| 141 | 146 | ||
| @@ -145,7 +150,7 @@ FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr | |||
| 145 | 150 | ||
| 146 | **描述** | 151 | **描述** |
| 147 | 152 | ||
| 148 | -初始化mutex。 | 153 | +初始化mutex。该mutex不再使用时，必须通过[ffrt_mutex_destroy](capi-mutex-h.md#ffrt_mutex_destroy)销毁。通过`attr`传入已配置的mutex属性，或传入空指针使用默认值。 |
| 149 | 154 | ||
| 150 | **起始版本：** 10 | 155 | **起始版本：** 10 |
| 151 | 156 | ||
| @@ -153,14 +158,14 @@ FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr | |||
| 153 | 158 | ||
| 154 | | 参数项 | 描述 | | 159 | | 参数项 | 描述 | |
| 155 | | -- | -- | | 160 | | -- | -- | |
| 156 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | mutex指针。 | | 161 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | 指向mutex的指针。 | |
| 157 | -| [const ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | mutex属性指针。 | | 162 | +| [const ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md)* attr | 指向mutex属性的指针，或传入空指针使用默认值。 | |
| 158 | 163 | ||
| 159 | **返回：** | 164 | **返回：** |
| 160 | 165 | ||
| 161 | | 类型 | 说明 | | 166 | | 类型 | 说明 | |
| 162 | | -- | -- | | 167 | | -- | -- | |
| 163 | -| FFRT_C_API int | 初始化mutex成功返回ffrt_success，<br> 初始化mutex失败返回ffrt_error_inval。 | | 168 | +| FFRT_C_API int | mutex初始化成功时返回`ffrt_success`；<br> `mutex`为空，或`attr`非空但未指定合法的mutex类型时返回`ffrt_error_inval`。 | |
| 164 | 169 | ||
| 165 | ### ffrt_mutex_lock() | 170 | ### ffrt_mutex_lock() |
| 166 | 171 | ||
| @@ -170,7 +175,7 @@ FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex) | |||
| 170 | 175 | ||
| 171 | **描述** | 176 | **描述** |
| 172 | 177 | ||
| 173 | -获取mutex。 | 178 | +加锁mutex。若mutex已被其他线程持有，则阻塞当前线程直到mutex可用。成功时，调用线程持有该mutex，直至通过[ffrt_mutex_unlock](capi-mutex-h.md#ffrt_mutex_unlock)释放。 |
| 174 | 179 | ||
| 175 | **起始版本：** 10 | 180 | **起始版本：** 10 |
| 176 | 181 | ||
| @@ -178,13 +183,18 @@ FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex) | |||
| 178 | 183 | ||
| 179 | | 参数项 | 描述 | | 184 | | 参数项 | 描述 | |
| 180 | | -- | -- | | 185 | | -- | -- | |
| 181 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | mutex指针。 | | 186 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | 指向mutex的指针。 | |
| 182 | 187 | ||
| 183 | **返回：** | 188 | **返回：** |
| 184 | 189 | ||
| 185 | | 类型 | 说明 | | 190 | | 类型 | 说明 | |
| 186 | | -- | -- | | 191 | | -- | -- | |
| 187 | -| FFRT_C_API int | 获取mutex成功返回ffrt_success，<br> 获取mutex失败返回ffrt_error_inval或者阻塞当前任务。 | | 192 | +| FFRT_C_API int | mutex加锁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 193 | + | ||
| 194 | +**参考：** | ||
| 195 | + | ||
| 196 | +[ffrt_mutex_trylock](capi-mutex-h.md#ffrt_mutex_trylock) | ||
| 197 | + | ||
| 188 | 198 | ||
| 189 | ### ffrt_mutex_unlock() | 199 | ### ffrt_mutex_unlock() |
| 190 | 200 | ||
| @@ -194,7 +204,7 @@ FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex) | |||
| 194 | 204 | ||
| 195 | **描述** | 205 | **描述** |
| 196 | 206 | ||
| 197 | -释放mutex。 | 207 | +解锁mutex。调用线程必须已持有该mutex，且该锁之前由[ffrt_mutex_lock](capi-mutex-h.md#ffrt_mutex_lock)或[ffrt_mutex_trylock](capi-mutex-h.md#ffrt_mutex_trylock)获取。 |
| 198 | 208 | ||
| 199 | **起始版本：** 10 | 209 | **起始版本：** 10 |
| 200 | 210 | ||
| @@ -202,13 +212,13 @@ FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex) | |||
| 202 | 212 | ||
| 203 | | 参数项 | 描述 | | 213 | | 参数项 | 描述 | |
| 204 | | -- | -- | | 214 | | -- | -- | |
| 205 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | mutex指针。 | | 215 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | 指向mutex的指针。 | |
| 206 | 216 | ||
| 207 | **返回：** | 217 | **返回：** |
| 208 | 218 | ||
| 209 | | 类型 | 说明 | | 219 | | 类型 | 说明 | |
| 210 | | -- | -- | | 220 | | -- | -- | |
| 211 | -| FFRT_C_API int | 释放mutex成功返回ffrt_success，<br> 释放mutex失败返回ffrt_error_inval。 | | 221 | +| FFRT_C_API int | mutex解锁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 212 | 222 | ||
| 213 | ### ffrt_mutex_trylock() | 223 | ### ffrt_mutex_trylock() |
| 214 | 224 | ||
| @@ -218,7 +228,7 @@ FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex) | |||
| 218 | 228 | ||
| 219 | **描述** | 229 | **描述** |
| 220 | 230 | ||
| 221 | -尝试获取mutex。 | 231 | +尝试加锁mutex。该接口为非阻塞操作：若mutex已被其他线程持有，则立即返回错误码。成功时，调用线程持有该mutex，直至通过[ffrt_mutex_unlock](capi-mutex-h.md#ffrt_mutex_unlock)释放。 |
| 222 | 232 | ||
| 223 | **起始版本：** 10 | 233 | **起始版本：** 10 |
| 224 | 234 | ||
| @@ -226,13 +236,18 @@ FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex) | |||
| 226 | 236 | ||
| 227 | | 参数项 | 描述 | | 237 | | 参数项 | 描述 | |
| 228 | | -- | -- | | 238 | | -- | -- | |
| 229 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | mutex指针。 | | 239 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | 指向mutex的指针。 | |
| 230 | 240 | ||
| 231 | **返回：** | 241 | **返回：** |
| 232 | 242 | ||
| 233 | | 类型 | 说明 | | 243 | | 类型 | 说明 | |
| 234 | | -- | -- | | 244 | | -- | -- | |
| 235 | -| FFRT_C_API int | 获取mutex成功返回ffrt_success，<br> 获取mutex失败返回ffrt_error_inval或ffrt_error_busy。 | | 245 | +| FFRT_C_API int | mutex加锁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`或`ffrt_error_busy`。 | |
| 246 | + | ||
| 247 | +**参考：** | ||
| 248 | + | ||
| 249 | +[ffrt_mutex_lock](capi-mutex-h.md#ffrt_mutex_lock) | ||
| 250 | + | ||
| 236 | 251 | ||
| 237 | ### ffrt_mutex_destroy() | 252 | ### ffrt_mutex_destroy() |
| 238 | 253 | ||
| @@ -242,7 +257,7 @@ FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex) | |||
| 242 | 257 | ||
| 243 | **描述** | 258 | **描述** |
| 244 | 259 | ||
| 245 | -销毁mutex。 | 260 | +销毁mutex。调用成功后，mutex占用的资源被释放，该mutex对象不可再使用。该mutex必须已通过[ffrt_mutex_init](capi-mutex-h.md#ffrt_mutex_init)初始化，且在调用本接口时不得被任何线程持有。 |
| 246 | 261 | ||
| 247 | **起始版本：** 10 | 262 | **起始版本：** 10 |
| 248 | 263 | ||
| @@ -250,12 +265,12 @@ FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex) | |||
| 250 | 265 | ||
| 251 | | 参数项 | 描述 | | 266 | | 参数项 | 描述 | |
| 252 | | -- | -- | | 267 | | -- | -- | |
| 253 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | mutex指针。 | | 268 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md)* mutex | 指向mutex的指针。 | |
| 254 | 269 | ||
| 255 | **返回：** | 270 | **返回：** |
| 256 | 271 | ||
| 257 | | 类型 | 说明 | | 272 | | 类型 | 说明 | |
| 258 | | -- | -- | | 273 | | -- | -- | |
| 259 | -| FFRT_C_API int | 销毁mutex成功返回ffrt_success，<br>销毁mutex失败返回ffrt_error_inval。 | | 274 | +| FFRT_C_API int | mutex销毁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 260 | 275 | ||
| 261 | 276 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| @@ -33,34 +33,34 @@ | |||
| 33 | 33 | ||
| 34 | | 名称 | typedef关键字 | 描述 | | 34 | | 名称 | typedef关键字 | 描述 | |
| 35 | | -- | -- | -- | | 35 | | -- | -- | -- | |
| 36 | -| [ffrt_queue_type_t](#ffrt_queue_type_t) | ffrt_queue_type_t | 队列类型。 | | 36 | +| [ffrt_queue_type_t](#ffrt_queue_type_t) | ffrt_queue_type_t | 枚举队列类型。 | |
| 37 | 37 | ||
| 38 | ### 函数 | 38 | ### 函数 |
| 39 | 39 | ||
| 40 | | 名称 | 描述 | | 40 | | 名称 | 描述 | |
| 41 | | -- | -- | | 41 | | -- | -- | |
| 42 | -| [FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_init) | 初始化队列属性。 | | 42 | +| [FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_init) | 初始化队列属性。该队列属性不再使用时，必须通过[ffrt_queue_attr_destroy](capi-queue-h.md#ffrt_queue_attr_destroy)销毁。 | |
| 43 | -| [FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_destroy) | 销毁队列属性。 | | 43 | +| [FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_destroy) | 销毁队列属性。该队列属性必须已通过[ffrt_queue_attr_init](capi-queue-h.md#ffrt_queue_attr_init)初始化。 | |
| 44 | -| [FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos)](#ffrt_queue_attr_set_qos) | 设置队列QoS属性。 | | 44 | +| [FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos)](#ffrt_queue_attr_set_qos) | 设置队列属性的QoS。 | |
| 45 | -| [FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_qos) | 获取队列QoS属性。 | | 45 | +| [FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_qos) | 获取队列属性的QoS。 | |
| 46 | -| [FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us)](#ffrt_queue_attr_set_timeout) | 设置串行队列timeout属性。超时时间的最小值是1ms，如果设置的值小于1ms，那么超时时间被设置为1ms。 | | 46 | +| [FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us)](#ffrt_queue_attr_set_timeout) | 设置队列属性的任务执行超时时长。 | |
| 47 | -| [FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_timeout) | 获取串行队列任务执行的timeout时间。 | | 47 | +| [FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_timeout) | 获取队列属性的任务执行超时时长。 | |
| 48 | -| [FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f)](#ffrt_queue_attr_set_callback) | 设置串行队列超时回调方法。<br> 不建议在`f`中调用`exit`函数，可能导致未定义行为。 | | 48 | +| [FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f)](#ffrt_queue_attr_set_callback) | 设置队列属性的超时回调函数。当队列中的任务执行时间超过通过[ffrt_queue_attr_set_timeout](capi-queue-h.md#ffrt_queue_attr_set_timeout)设置的超时时长时触发该回调。 | |
| 49 | -| [FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_callback) | 获取串行队列超时回调方法。 | | 49 | +| [FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_callback) | 获取队列属性的超时回调函数。 | |
| 50 | -| [FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency)](#ffrt_queue_attr_set_max_concurrency) | 设置并行队列最大并发度。 | | 50 | +| [FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency)](#ffrt_queue_attr_set_max_concurrency) | 设置并发队列属性的最大并发度。 | |
| 51 | -| [FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_max_concurrency) | 获取并行队列最大并发度。 | | 51 | +| [FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_max_concurrency) | 获取并发队列属性的最大并发度。 | |
| 52 | -| [FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mode)](#ffrt_queue_attr_set_thread_mode) | 设置队列中的任务是以协程模式还是以线程模式运行。默认以协程模式运行。 | | 52 | +| [FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mode)](#ffrt_queue_attr_set_thread_mode) | 设置队列属性的执行模式。该接口指定队列中的任务是以协程模式还是线程模式执行。默认以协程模式执行。将mode设为`true`时启用基于线程的执行。 | |
| 53 | -| [FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_thread_mode) | 获取队列中的任务是以协程模式还是以线程模式运行。 | | 53 | +| [FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_thread_mode) | 获取队列属性的执行模式。 | |
| 54 | -| [FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr)](#ffrt_queue_create) | 创建队列。 | | 54 | +| [FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr)](#ffrt_queue_create) | 创建队列。该队列不再使用时，必须通过[ffrt_queue_destroy](capi-queue-h.md#ffrt_queue_destroy)销毁。 | |
| 55 | -| [FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue)](#ffrt_queue_destroy) | 销毁队列。 | | 55 | +| [FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue)](#ffrt_queue_destroy) | 销毁队列。该队列必须已通过[ffrt_queue_create](capi-queue-h.md#ffrt_queue_create)创建。销毁时会取消尚未开始执行的任务，并阻塞等待正在执行的任务完成。 | |
| 56 | -| [FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)](#ffrt_queue_submit) | 提交一个任务到队列中调度执行。 | | 56 | +| [FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)](#ffrt_queue_submit) | 提交任务到队列。 | |
| 57 | -| [FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_h) | 提交一个任务到队列中调度执行，并返回任务句柄。 | | 57 | +| [FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_h) | 提交任务到队列，并获取任务句柄。 | |
| 58 | -| [FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_f) | 提交一个任务到队列中调度执行，是ffrt_queue_submit接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit接口。 | | 58 | +| [FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_f) | 提交任务到队列，是[ffrt_queue_submit](capi-queue-h.md#ffrt_queue_submit)接口的简化形式。该接口将给定的任务函数及其参数包装为用于队列提交的任务包装器（`ffrt_function_kind_queue`）。其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。生成的任务包装器随后通过[ffrt_queue_submit](capi-queue-h.md#ffrt_queue_submit)接口被提交到指定队列。 | |
| 59 | -| [FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_h_f) | 提交一个任务到队列中调度执行，并返回任务句柄，是ffrt_queue_submit_h接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit_h接口。 | | 59 | +| [FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_h_f) | 提交任务到队列并获取任务句柄，是[ffrt_queue_submit_h](capi-queue-h.md#ffrt_queue_submit_h)接口的简化形式。该接口将给定的任务函数及其参数包装为用于队列提交的任务包装器（`ffrt_function_kind_queue`）。其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。生成的任务包装器随后通过[ffrt_queue_submit_h](capi-queue-h.md#ffrt_queue_submit_h)接口被提交到指定队列。 | |
| 60 | -| [FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle)](#ffrt_queue_wait) | 等待队列中一个任务执行完成。 | | 60 | +| [FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle)](#ffrt_queue_wait) | 等待队列中的任务执行完成。 | |
| 61 | -| [FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle)](#ffrt_queue_cancel) | 取消队列中一个任务。 | | 61 | +| [FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle)](#ffrt_queue_cancel) | 取消队列中的任务。已开始执行的任务无法被取消。 | |
| 62 | -| [FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void)](#ffrt_get_main_queue) | 获取主线程队列。 | | 62 | +| [FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void)](#ffrt_get_main_queue) | 获取应用主线程队列。 | |
| 63 | -| [FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void)](#ffrt_get_current_queue) | 获取应用Worker(ArkTs)线程队列。(API18废弃) | | 63 | +| [FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void)](#ffrt_get_current_queue) | 获取应用Worker（ArkTS）线程队列。(API18废弃) | |
| 64 | 64 | ||
| 65 | ## 枚举类型说明 | 65 | ## 枚举类型说明 |
| 66 | 66 | ||
| @@ -72,15 +72,15 @@ enum ffrt_queue_type_t | |||
| 72 | 72 | ||
| 73 | **描述** | 73 | **描述** |
| 74 | 74 | ||
| 75 | -队列类型。 | 75 | +枚举队列类型。 |
| 76 | 76 | ||
| 77 | **起始版本：** 12 | 77 | **起始版本：** 12 |
| 78 | 78 | ||
| 79 | | 枚举项 | 描述 | | 79 | | 枚举项 | 描述 | |
| 80 | | -- | -- | | 80 | | -- | -- | |
| 81 | -| ffrt_queue_serial | 串行队列 | | 81 | +| ffrt_queue_serial | 串行队列。 | |
| 82 | -| ffrt_queue_concurrent | 并行队列 | | 82 | +| ffrt_queue_concurrent | 并发队列。 | |
| 83 | -| ffrt_queue_max | 无效队列类型 | | 83 | +| ffrt_queue_max | 最大有效队列类型值，作为哨兵使用（例如用于迭代）。 | |
| 84 | 84 | ||
| 85 | 85 | ||
| 86 | ## 函数说明 | 86 | ## 函数说明 |
| @@ -93,7 +93,7 @@ FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr) | |||
| 93 | 93 | ||
| 94 | **描述** | 94 | **描述** |
| 95 | 95 | ||
| 96 | -初始化队列属性。 | 96 | +初始化队列属性。该队列属性不再使用时，必须通过[ffrt_queue_attr_destroy](capi-queue-h.md#ffrt_queue_attr_destroy)销毁。 |
| 97 | 97 | ||
| 98 | **起始版本：** 10 | 98 | **起始版本：** 10 |
| 99 | 99 | ||
| @@ -101,13 +101,13 @@ FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr) | |||
| 101 | 101 | ||
| 102 | | 参数项 | 描述 | | 102 | | 参数项 | 描述 | |
| 103 | | -- | -- | | 103 | | -- | -- | |
| 104 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 104 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 105 | 105 | ||
| 106 | **返回：** | 106 | **返回：** |
| 107 | 107 | ||
| 108 | | 类型 | 说明 | | 108 | | 类型 | 说明 | |
| 109 | | -- | -- | | 109 | | -- | -- | |
| 110 | -| FFRT_C_API int | 执行成功时返回0，<br> 执行失败时返回-1。 | | 110 | +| FFRT_C_API int | 队列属性初始化成功时返回`0`；<br> 否则返回`-1`。 | |
| 111 | 111 | ||
| 112 | ### ffrt_queue_attr_destroy() | 112 | ### ffrt_queue_attr_destroy() |
| 113 | 113 | ||
| @@ -117,7 +117,7 @@ FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr) | |||
| 117 | 117 | ||
| 118 | **描述** | 118 | **描述** |
| 119 | 119 | ||
| 120 | -销毁队列属性。 | 120 | +销毁队列属性。该队列属性必须已通过[ffrt_queue_attr_init](capi-queue-h.md#ffrt_queue_attr_init)初始化。 |
| 121 | 121 | ||
| 122 | **起始版本：** 10 | 122 | **起始版本：** 10 |
| 123 | 123 | ||
| @@ -125,7 +125,7 @@ FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr) | |||
| 125 | 125 | ||
| 126 | | 参数项 | 描述 | | 126 | | 参数项 | 描述 | |
| 127 | | -- | -- | | 127 | | -- | -- | |
| 128 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 128 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 129 | 129 | ||
| 130 | ### ffrt_queue_attr_set_qos() | 130 | ### ffrt_queue_attr_set_qos() |
| 131 | 131 | ||
| @@ -135,7 +135,7 @@ FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos) | |||
| 135 | 135 | ||
| 136 | **描述** | 136 | **描述** |
| 137 | 137 | ||
| 138 | -设置队列QoS属性。 | 138 | +设置队列属性的QoS。 |
| 139 | 139 | ||
| 140 | **起始版本：** 10 | 140 | **起始版本：** 10 |
| 141 | 141 | ||
| @@ -143,8 +143,8 @@ FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos) | |||
| 143 | 143 | ||
| 144 | | 参数项 | 描述 | | 144 | | 参数项 | 描述 | |
| 145 | | -- | -- | | 145 | | -- | -- | |
| 146 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 146 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 147 | -| [ffrt_qos_t](capi-type-def-h.md#变量) qos | QoS属性值。 | | 147 | +| [ffrt_qos_t](capi-type-def-h.md#变量) qos | QoS等级，取值范围参见[ffrt_qos_t](capi-type-def-h.md#变量)枚举定义。 | |
| 148 | 148 | ||
| 149 | ### ffrt_queue_attr_get_qos() | 149 | ### ffrt_queue_attr_get_qos() |
| 150 | 150 | ||
| @@ -154,7 +154,7 @@ FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr) | |||
| 154 | 154 | ||
| 155 | **描述** | 155 | **描述** |
| 156 | 156 | ||
| 157 | -获取队列QoS属性。 | 157 | +获取队列属性的QoS。 |
| 158 | 158 | ||
| 159 | **起始版本：** 10 | 159 | **起始版本：** 10 |
| 160 | 160 | ||
| @@ -162,13 +162,13 @@ FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr) | |||
| 162 | 162 | ||
| 163 | | 参数项 | 描述 | | 163 | | 参数项 | 描述 | |
| 164 | | -- | -- | | 164 | | -- | -- | |
| 165 | -| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 165 | +| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 166 | 166 | ||
| 167 | **返回：** | 167 | **返回：** |
| 168 | 168 | ||
| 169 | | 类型 | 说明 | | 169 | | 类型 | 说明 | |
| 170 | | -- | -- | | 170 | | -- | -- | |
| 171 | -| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | 返回队列的QoS属性。 | | 171 | +| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | QoS等级，取值范围参见[ffrt_qos_t](capi-type-def-h.md#变量)枚举定义。 | |
| 172 | 172 | ||
| 173 | ### ffrt_queue_attr_set_timeout() | 173 | ### ffrt_queue_attr_set_timeout() |
| 174 | 174 | ||
| @@ -178,7 +178,7 @@ FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t ti | |||
| 178 | 178 | ||
| 179 | **描述** | 179 | **描述** |
| 180 | 180 | ||
| 181 | -设置串行队列timeout属性。超时时间的最小值是1ms，如果设置的值小于1ms，那么超时时间被设置为1ms。 | 181 | +设置队列属性的任务执行超时时长。 |
| 182 | 182 | ||
| 183 | **起始版本：** 10 | 183 | **起始版本：** 10 |
| 184 | 184 | ||
| @@ -186,8 +186,8 @@ FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t ti | |||
| 186 | 186 | ||
| 187 | | 参数项 | 描述 | | 187 | | 参数项 | 描述 | |
| 188 | | -- | -- | | 188 | | -- | -- | |
| 189 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | | 189 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 190 | -| uint64_t timeout_us | 串行队列任务执行的timeout时间(微秒)。 | | 190 | +| uint64_t timeout_us | 队列任务执行超时时长，单位是微秒。下限为1000微秒（1毫秒），低于1000的值会被强制设为1000。 | |
| 191 | 191 | ||
| 192 | ### ffrt_queue_attr_get_timeout() | 192 | ### ffrt_queue_attr_get_timeout() |
| 193 | 193 | ||
| @@ -197,7 +197,7 @@ FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr) | |||
| 197 | 197 | ||
| 198 | **描述** | 198 | **描述** |
| 199 | 199 | ||
| 200 | -获取串行队列任务执行的timeout时间。 | 200 | +获取队列属性的任务执行超时时长。 |
| 201 | 201 | ||
| 202 | **起始版本：** 10 | 202 | **起始版本：** 10 |
| 203 | 203 | ||
| @@ -205,13 +205,13 @@ FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr) | |||
| 205 | 205 | ||
| 206 | | 参数项 | 描述 | | 206 | | 参数项 | 描述 | |
| 207 | | -- | -- | | 207 | | -- | -- | |
| 208 | -| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | | 208 | +| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 209 | 209 | ||
| 210 | **返回：** | 210 | **返回：** |
| 211 | 211 | ||
| 212 | | 类型 | 说明 | | 212 | | 类型 | 说明 | |
| 213 | | -- | -- | | 213 | | -- | -- | |
| 214 | -| FFRT_C_API uint64_t | 返回串行队列任务执行的timeout时间。 | | 214 | +| FFRT_C_API uint64_t | 队列任务执行超时时长，单位是微秒。 | |
| 215 | 215 | ||
| 216 | ### ffrt_queue_attr_set_callback() | 216 | ### ffrt_queue_attr_set_callback() |
| 217 | 217 | ||
| @@ -221,9 +221,7 @@ FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_funct | |||
| 221 | 221 | ||
| 222 | **描述** | 222 | **描述** |
| 223 | 223 | ||
| 224 | -设置串行队列超时回调方法。 | 224 | +设置队列属性的超时回调函数。当队列中的任务执行时间超过通过[ffrt_queue_attr_set_timeout](capi-queue-h.md#ffrt_queue_attr_set_timeout)设置的超时时长时触发该回调。 |
| 225 | - | ||
| 226 | -不建议在`f`中调用`exit`函数，可能导致未定义行为。 | ||
| 227 | 225 | ||
| 228 | **起始版本：** 10 | 226 | **起始版本：** 10 |
| 229 | 227 | ||
| @@ -231,8 +229,8 @@ FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_funct | |||
| 231 | 229 | ||
| 232 | | 参数项 | 描述 | | 230 | | 参数项 | 描述 | |
| 233 | | -- | -- | | 231 | | -- | -- | |
| 234 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | | 232 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 235 | -| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 超时回调方法执行体。 | | 233 | +| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 队列超时回调函数。 | |
| 236 | 234 | ||
| 237 | ### ffrt_queue_attr_get_callback() | 235 | ### ffrt_queue_attr_get_callback() |
| 238 | 236 | ||
| @@ -242,7 +240,7 @@ FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue | |||
| 242 | 240 | ||
| 243 | **描述** | 241 | **描述** |
| 244 | 242 | ||
| 245 | -获取串行队列超时回调方法。 | 243 | +获取队列属性的超时回调函数。 |
| 246 | 244 | ||
| 247 | **起始版本：** 10 | 245 | **起始版本：** 10 |
| 248 | 246 | ||
| @@ -250,13 +248,13 @@ FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue | |||
| 250 | 248 | ||
| 251 | | 参数项 | 描述 | | 249 | | 参数项 | 描述 | |
| 252 | | -- | -- | | 250 | | -- | -- | |
| 253 | -| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | | 251 | +| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 254 | 252 | ||
| 255 | **返回：** | 253 | **返回：** |
| 256 | 254 | ||
| 257 | | 类型 | 说明 | | 255 | | 类型 | 说明 | |
| 258 | | -- | -- | | 256 | | -- | -- | |
| 259 | -| FFRT_C_API [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* | 返回串行队列超时回调方法。 | | 257 | +| FFRT_C_API [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* | 队列任务超时回调函数。 | |
| 260 | 258 | ||
| 261 | ### ffrt_queue_attr_set_max_concurrency() | 259 | ### ffrt_queue_attr_set_max_concurrency() |
| 262 | 260 | ||
| @@ -266,7 +264,7 @@ FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, con | |||
| 266 | 264 | ||
| 267 | **描述** | 265 | **描述** |
| 268 | 266 | ||
| 269 | -设置并行队列最大并发度。 | 267 | +设置并发队列属性的最大并发度。 |
| 270 | 268 | ||
| 271 | **起始版本：** 12 | 269 | **起始版本：** 12 |
| 272 | 270 | ||
| @@ -274,8 +272,8 @@ FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, con | |||
| 274 | 272 | ||
| 275 | | 参数项 | 描述 | | 273 | | 参数项 | 描述 | |
| 276 | | -- | -- | | 274 | | -- | -- | |
| 277 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 275 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 278 | -| const int max_concurrency | 最大并发度。 | | 276 | +| const int max_concurrency | 队列可并发执行的最大任务数。 | |
| 279 | 277 | ||
| 280 | ### ffrt_queue_attr_get_max_concurrency() | 278 | ### ffrt_queue_attr_get_max_concurrency() |
| 281 | 279 | ||
| @@ -285,7 +283,7 @@ FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr | |||
| 285 | 283 | ||
| 286 | **描述** | 284 | **描述** |
| 287 | 285 | ||
| 288 | -获取并行队列最大并发度。 | 286 | +获取并发队列属性的最大并发度。 |
| 289 | 287 | ||
| 290 | **起始版本：** 12 | 288 | **起始版本：** 12 |
| 291 | 289 | ||
| @@ -293,13 +291,13 @@ FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr | |||
| 293 | 291 | ||
| 294 | | 参数项 | 描述 | | 292 | | 参数项 | 描述 | |
| 295 | | -- | -- | | 293 | | -- | -- | |
| 296 | -| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 294 | +| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 297 | 295 | ||
| 298 | **返回：** | 296 | **返回：** |
| 299 | 297 | ||
| 300 | | 类型 | 说明 | | 298 | | 类型 | 说明 | |
| 301 | | -- | -- | | 299 | | -- | -- | |
| 302 | -| FFRT_C_API int | 返回最大并发度。 | | 300 | +| FFRT_C_API int | 队列的最大并发度。 | |
| 303 | 301 | ||
| 304 | ### ffrt_queue_attr_set_thread_mode() | 302 | ### ffrt_queue_attr_set_thread_mode() |
| 305 | 303 | ||
| @@ -309,7 +307,7 @@ FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mo | |||
| 309 | 307 | ||
| 310 | **描述** | 308 | **描述** |
| 311 | 309 | ||
| 312 | -设置队列中的任务是以协程模式还是以线程模式运行。默认以协程模式运行。 | 310 | +设置队列属性的执行模式。该接口指定队列中的任务是以协程模式还是线程模式执行。默认以协程模式执行。将mode设为`true`时启用基于线程的执行。 |
| 313 | 311 | ||
| 314 | **起始版本：** 20 | 312 | **起始版本：** 20 |
| 315 | 313 | ||
| @@ -317,8 +315,8 @@ FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mo | |||
| 317 | 315 | ||
| 318 | | 参数项 | 描述 | | 316 | | 参数项 | 描述 | |
| 319 | | -- | -- | | 317 | | -- | -- | |
| 320 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 318 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 321 | -| bool mode | 设置队列任务运行方式。true表示以线程模式运行；false表示以协程方式运行。 | | 319 | +| bool mode | 是否启用基于线程的执行模式。- `true`：任务以原生线程执行（线程模式）。- `false`：任务以协程执行（默认）。 | |
| 322 | 320 | ||
| 323 | ### ffrt_queue_attr_get_thread_mode() | 321 | ### ffrt_queue_attr_get_thread_mode() |
| 324 | 322 | ||
| @@ -328,7 +326,7 @@ FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr) | |||
| 328 | 326 | ||
| 329 | **描述** | 327 | **描述** |
| 330 | 328 | ||
| 331 | -获取队列中的任务是以协程模式还是以线程模式运行。 | 329 | +获取队列属性的执行模式。 |
| 332 | 330 | ||
| 333 | **起始版本：** 20 | 331 | **起始版本：** 20 |
| 334 | 332 | ||
| @@ -336,13 +334,13 @@ FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr) | |||
| 336 | 334 | ||
| 337 | | 参数项 | 描述 | | 335 | | 参数项 | 描述 | |
| 338 | | -- | -- | | 336 | | -- | -- | |
| 339 | -| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | | 337 | +| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 340 | 338 | ||
| 341 | **返回：** | 339 | **返回：** |
| 342 | 340 | ||
| 343 | | 类型 | 说明 | | 341 | | 类型 | 说明 | |
| 344 | | -- | -- | | 342 | | -- | -- | |
| 345 | -| FFRT_C_API bool | true表示以线程模式运行，false表示以协程模式运行。 | | 343 | +| FFRT_C_API bool | 任务以原生线程执行（线程模式）时返回`true`；<br> 任务以协程执行（默认）时返回`false`。 | |
| 346 | 344 | ||
| 347 | ### ffrt_queue_create() | 345 | ### ffrt_queue_create() |
| 348 | 346 | ||
| @@ -352,7 +350,7 @@ FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* na | |||
| 352 | 350 | ||
| 353 | **描述** | 351 | **描述** |
| 354 | 352 | ||
| 355 | -创建队列。 | 353 | +创建队列。该队列不再使用时，必须通过[ffrt_queue_destroy](capi-queue-h.md#ffrt_queue_destroy)销毁。 |
| 356 | 354 | ||
| 357 | **起始版本：** 10 | 355 | **起始版本：** 10 |
| 358 | 356 | ||
| @@ -360,15 +358,15 @@ FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* na | |||
| 360 | 358 | ||
| 361 | | 参数项 | 描述 | | 359 | | 参数项 | 描述 | |
| 362 | | -- | -- | | 360 | | -- | -- | |
| 363 | -| [ffrt_queue_type_t](capi-queue-h.md#ffrt_queue_type_t) type | 队列类型。 | | 361 | +| [ffrt_queue_type_t](capi-queue-h.md#ffrt_queue_type_t) type | 队列类型。`ffrt_queue_serial`适用于任务需按顺序执行的场景；`ffrt_queue_concurrent`适用于任务可并发执行以提高吞吐量的场景。 | |
| 364 | -| const char* name | 队列名字。 | | 362 | +| const char* name | 指向队列名称的指针。 | |
| 365 | -| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性。 | | 363 | +| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 指向队列属性的指针。 | |
| 366 | 364 | ||
| 367 | **返回：** | 365 | **返回：** |
| 368 | 366 | ||
| 369 | | 类型 | 说明 | | 367 | | 类型 | 说明 | |
| 370 | | -- | -- | | 368 | | -- | -- | |
| 371 | -| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | 创建队列成功返回非空队列句柄，<br> 创建队列失败返回空指针。 | | 369 | +| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | 队列创建成功时返回非空的队列句柄；<br> 否则返回空指针。 | |
| 372 | 370 | ||
| 373 | ### ffrt_queue_destroy() | 371 | ### ffrt_queue_destroy() |
| 374 | 372 | ||
| @@ -378,7 +376,7 @@ FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue) | |||
| 378 | 376 | ||
| 379 | **描述** | 377 | **描述** |
| 380 | 378 | ||
| 381 | -销毁队列。 | 379 | +销毁队列。该队列必须已通过[ffrt_queue_create](capi-queue-h.md#ffrt_queue_create)创建。销毁时会取消尚未开始执行的任务，并阻塞等待正在执行的任务完成。 |
| 382 | 380 | ||
| 383 | **起始版本：** 10 | 381 | **起始版本：** 10 |
| 384 | 382 | ||
| @@ -396,7 +394,7 @@ FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, | |||
| 396 | 394 | ||
| 397 | **描述** | 395 | **描述** |
| 398 | 396 | ||
| 399 | -提交一个任务到队列中调度执行。 | 397 | +提交任务到队列。 |
| 400 | 398 | ||
| 401 | **起始版本：** 10 | 399 | **起始版本：** 10 |
| 402 | 400 | ||
| @@ -405,8 +403,13 @@ FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, | |||
| 405 | | 参数项 | 描述 | | 403 | | 参数项 | 描述 | |
| 406 | | -- | -- | | 404 | | -- | -- | |
| 407 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | | 405 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | |
| 408 | -| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务的执行体。 | | 406 | +| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 指向任务执行体的指针。 | |
| 409 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 407 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 408 | + | ||
| 409 | +**参考：** | ||
| 410 | + | ||
| 411 | +[ffrt_queue_submit_h](capi-queue-h.md#ffrt_queue_submit_h) | ||
| 412 | + | ||
| 410 | 413 | ||
| 411 | ### ffrt_queue_submit_h() | 414 | ### ffrt_queue_submit_h() |
| 412 | 415 | ||
| @@ -416,7 +419,7 @@ FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h(ffrt_queue_t queue, ffrt_funct | |||
| 416 | 419 | ||
| 417 | **描述** | 420 | **描述** |
| 418 | 421 | ||
| 419 | -提交一个任务到队列中调度执行，并返回任务句柄。 | 422 | +提交任务到队列，并获取任务句柄。 |
| 420 | 423 | ||
| 421 | **起始版本：** 10 | 424 | **起始版本：** 10 |
| 422 | 425 | ||
| @@ -425,14 +428,19 @@ FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h(ffrt_queue_t queue, ffrt_funct | |||
| 425 | | 参数项 | 描述 | | 428 | | 参数项 | 描述 | |
| 426 | | -- | -- | | 429 | | -- | -- | |
| 427 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | | 430 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | |
| 428 | -| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务的执行体。 | | 431 | +| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 指向任务执行体的指针。 | |
| 429 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 432 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 430 | 433 | ||
| 431 | **返回：** | 434 | **返回：** |
| 432 | 435 | ||
| 433 | | 类型 | 说明 | | 436 | | 类型 | 说明 | |
| 434 | | -- | -- | | 437 | | -- | -- | |
| 435 | -| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交成功返回非空任务句柄，<br> 提交失败返回空指针。 | | 438 | +| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 任务提交成功时返回非空的任务句柄；<br> 否则返回空指针。 | |
| 439 | + | ||
| 440 | +**参考：** | ||
| 441 | + | ||
| 442 | +[ffrt_queue_submit](capi-queue-h.md#ffrt_queue_submit) | ||
| 443 | + | ||
| 436 | 444 | ||
| 437 | ### ffrt_queue_submit_f() | 445 | ### ffrt_queue_submit_f() |
| 438 | 446 | ||
| @@ -442,7 +450,7 @@ FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, vo | |||
| 442 | 450 | ||
| 443 | **描述** | 451 | **描述** |
| 444 | 452 | ||
| 445 | -提交一个任务到队列中调度执行，是ffrt_queue_submit接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit接口。 | 453 | +提交任务到队列，是[ffrt_queue_submit](capi-queue-h.md#ffrt_queue_submit)接口的简化形式。该接口将给定的任务函数及其参数包装为用于队列提交的任务包装器（`ffrt_function_kind_queue`）。其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。生成的任务包装器随后通过[ffrt_queue_submit](capi-queue-h.md#ffrt_queue_submit)接口被提交到指定队列。 |
| 446 | 454 | ||
| 447 | **起始版本：** 20 | 455 | **起始版本：** 20 |
| 448 | 456 | ||
| @@ -451,9 +459,9 @@ FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, vo | |||
| 451 | | 参数项 | 描述 | | 459 | | 参数项 | 描述 | |
| 452 | | -- | -- | | 460 | | -- | -- | |
| 453 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | | 461 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | |
| 454 | -| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | | 462 | +| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 要执行的任务函数。 | |
| 455 | -| void* arg | 传递给任务函数的参数。 | | 463 | +| void* arg | 指向传递给任务函数的参数或闭包数据的指针。 | |
| 456 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 464 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 457 | 465 | ||
| 458 | **参考：** | 466 | **参考：** |
| 459 | 467 | ||
| @@ -468,7 +476,7 @@ FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f(ffrt_queue_t queue, ffrt_fun | |||
| 468 | 476 | ||
| 469 | **描述** | 477 | **描述** |
| 470 | 478 | ||
| 471 | -提交一个任务到队列中调度执行，并返回任务句柄，是ffrt_queue_submit_h接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit_h接口。 | 479 | +提交任务到队列并获取任务句柄，是[ffrt_queue_submit_h](capi-queue-h.md#ffrt_queue_submit_h)接口的简化形式。该接口将给定的任务函数及其参数包装为用于队列提交的任务包装器（`ffrt_function_kind_queue`）。其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。生成的任务包装器随后通过[ffrt_queue_submit_h](capi-queue-h.md#ffrt_queue_submit_h)接口被提交到指定队列。 |
| 472 | 480 | ||
| 473 | **起始版本：** 20 | 481 | **起始版本：** 20 |
| 474 | 482 | ||
| @@ -477,15 +485,15 @@ FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f(ffrt_queue_t queue, ffrt_fun | |||
| 477 | | 参数项 | 描述 | | 485 | | 参数项 | 描述 | |
| 478 | | -- | -- | | 486 | | -- | -- | |
| 479 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | | 487 | | [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | |
| 480 | -| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | | 488 | +| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 要执行的任务函数。 | |
| 481 | -| void* arg | 传递给任务函数的参数。 | | 489 | +| void* arg | 指向传递给任务函数的参数或闭包数据的指针。 | |
| 482 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 490 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 483 | 491 | ||
| 484 | **返回：** | 492 | **返回：** |
| 485 | 493 | ||
| 486 | | 类型 | 说明 | | 494 | | 类型 | 说明 | |
| 487 | | -- | -- | | 495 | | -- | -- | |
| 488 | -| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交成功返回非空任务句柄，<br> 提交失败返回空指针。 | | 496 | +| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 任务提交成功时返回非空的任务句柄；<br> 否则返回空指针。 | |
| 489 | 497 | ||
| 490 | **参考：** | 498 | **参考：** |
| 491 | 499 | ||
| @@ -500,7 +508,7 @@ FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle) | |||
| 500 | 508 | ||
| 501 | **描述** | 509 | **描述** |
| 502 | 510 | ||
| 503 | -等待队列中一个任务执行完成。 | 511 | +等待队列中的任务执行完成。 |
| 504 | 512 | ||
| 505 | **起始版本：** 10 | 513 | **起始版本：** 10 |
| 506 | 514 | ||
| @@ -518,7 +526,7 @@ FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle) | |||
| 518 | 526 | ||
| 519 | **描述** | 527 | **描述** |
| 520 | 528 | ||
| 521 | -取消队列中一个任务。 | 529 | +取消队列中的任务。已开始执行的任务无法被取消。 |
| 522 | 530 | ||
| 523 | **起始版本：** 10 | 531 | **起始版本：** 10 |
| 524 | 532 | ||
| @@ -532,7 +540,7 @@ FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle) | |||
| 532 | 540 | ||
| 533 | | 类型 | 说明 | | 541 | | 类型 | 说明 | |
| 534 | | -- | -- | | 542 | | -- | -- | |
| 535 | -| FFRT_C_API int | 取消任务成功返回0，<br> 取消任务失败返回-1。 | | 543 | +| FFRT_C_API int | 任务取消成功时返回`0`；<br> 任务已执行完毕或已从队列中移除时返回`1`；<br> handle为空时返回`-1`。 | |
| 536 | 544 | ||
| 537 | ### ffrt_get_main_queue() | 545 | ### ffrt_get_main_queue() |
| 538 | 546 | ||
| @@ -542,7 +550,7 @@ FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void) | |||
| 542 | 550 | ||
| 543 | **描述** | 551 | **描述** |
| 544 | 552 | ||
| 545 | -获取主线程队列。 | 553 | +获取应用主线程队列。 |
| 546 | 554 | ||
| 547 | **起始版本：** 12 | 555 | **起始版本：** 12 |
| 548 | 556 | ||
| @@ -550,7 +558,7 @@ FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void) | |||
| 550 | 558 | ||
| 551 | | 类型 | 说明 | | 559 | | 类型 | 说明 | |
| 552 | | -- | -- | | 560 | | -- | -- | |
| 553 | -| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | 返回主线程队列句柄。 | | 561 | +| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | 应用主线程队列。 | |
| 554 | 562 | ||
| 555 | ### ffrt_get_current_queue() | 563 | ### ffrt_get_current_queue() |
| 556 | 564 | ||
| @@ -560,7 +568,7 @@ FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void) | |||
| 560 | 568 | ||
| 561 | **描述** | 569 | **描述** |
| 562 | 570 | ||
| 563 | -获取应用Worker(ArkTs)线程队列。 | 571 | +获取应用Worker（ArkTS）线程队列。 |
| 564 | 572 | ||
| 565 | **起始版本：** 12 | 573 | **起始版本：** 12 |
| 566 | 574 | ||
| @@ -570,6 +578,6 @@ FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void) | |||
| 570 | 578 | ||
| 571 | | 类型 | 说明 | | 579 | | 类型 | 说明 | |
| 572 | | -- | -- | | 580 | | -- | -- | |
| 573 | -| FFRT_C_API ffrt_queue_t | 返回当前线程队列句柄。 | | 581 | +| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | 应用Worker（ArkTS）线程队列。 | |
| 574 | 582 | ||
| 575 | 583 | ||
| @@ -2,14 +2,14 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| 11 | 11 | ||
| 12 | -声明rwlock的C接口。 | 12 | +声明读写锁（rwlock）的C接口。 |
| 13 | 13 | ||
| 14 | **引用文件：** <ffrt/shared_mutex.h> | 14 | **引用文件：** <ffrt/shared_mutex.h> |
| 15 | 15 | ||
| @@ -27,13 +27,13 @@ | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [FFRT_C_API int ffrt_rwlock_init(ffrt_rwlock_t* rwlock, const ffrt_rwlockattr_t* attr)](#ffrt_rwlock_init) | 初始化rwlock。 | | 30 | +| [FFRT_C_API int ffrt_rwlock_init(ffrt_rwlock_t* rwlock, const ffrt_rwlockattr_t* attr)](#ffrt_rwlock_init) | 初始化rwlock。该rwlock不再使用时，必须通过[ffrt_rwlock_destroy](capi-shared-mutex-h.md#ffrt_rwlock_destroy)销毁。 | |
| 31 | -| [FFRT_C_API int ffrt_rwlock_wrlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_wrlock) | 获取写锁。 | | 31 | +| [FFRT_C_API int ffrt_rwlock_wrlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_wrlock) | 加写锁。锁不可用时阻塞当前线程。成功时，调用线程持有排他写锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。写锁具有排他性，不允许与任何读锁同时持有。 | |
 应该是：排它？ 需要修改的话同步改一下header哦。  mazhabandeng 7月13日 评论： 7月13日 评论： | |||
| 32 | -| [FFRT_C_API int ffrt_rwlock_trywrlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_trywrlock) | 尝试获取写锁。 | | 32 | +| [FFRT_C_API int ffrt_rwlock_trywrlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_trywrlock) | 尝试加写锁。不会阻塞当前线程。成功时，调用线程持有排他写锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。 | |
| 33 | -| [FFRT_C_API int ffrt_rwlock_rdlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_rdlock) | 获取读锁。 | | 33 | +| [FFRT_C_API int ffrt_rwlock_rdlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_rdlock) | 加读锁。锁不可用时阻塞当前线程。成功时，调用线程持有读锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。多个读者可同时持有该锁，但不允许与写锁同时持有。 | |
| 34 | -| [FFRT_C_API int ffrt_rwlock_tryrdlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_tryrdlock) | 尝试获取读锁。 | | 34 | +| [FFRT_C_API int ffrt_rwlock_tryrdlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_tryrdlock) | 尝试加读锁。不会阻塞当前线程。成功时，调用线程持有读锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。 | |
| 35 | -| [FFRT_C_API int ffrt_rwlock_unlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_unlock) | 释放rwlock。 | | 35 | +| [FFRT_C_API int ffrt_rwlock_unlock(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_unlock) | 解锁rwlock。调用线程必须已持有该rwlock，且该锁之前由[ffrt_rwlock_rdlock](capi-shared-mutex-h.md#ffrt_rwlock_rdlock)、[ffrt_rwlock_tryrdlock](capi-shared-mutex-h.md#ffrt_rwlock_tryrdlock)、[ffrt_rwlock_wrlock](capi-shared-mutex-h.md#ffrt_rwlock_wrlock)或[ffrt_rwlock_trywrlock](capi-shared-mutex-h.md#ffrt_rwlock_trywrlock)获取。 | |
| 36 | -| [FFRT_C_API int ffrt_rwlock_destroy(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_destroy) | 销毁rwlock。 | | 36 | +| [FFRT_C_API int ffrt_rwlock_destroy(ffrt_rwlock_t* rwlock)](#ffrt_rwlock_destroy) | 销毁rwlock。该rwlock必须已通过[ffrt_rwlock_init](capi-shared-mutex-h.md#ffrt_rwlock_init)初始化，且在调用本接口时不得被任何线程以读锁或写锁持有。 | |
| 37 | 37 | ||
| 38 | ## 函数说明 | 38 | ## 函数说明 |
| 39 | 39 | ||
| @@ -45,7 +45,7 @@ FFRT_C_API int ffrt_rwlock_init(ffrt_rwlock_t* rwlock, const ffrt_rwlockattr_t* | |||
| 45 | 45 | ||
| 46 | **描述** | 46 | **描述** |
| 47 | 47 | ||
| 48 | -初始化rwlock。 | 48 | +初始化rwlock。该rwlock不再使用时，必须通过[ffrt_rwlock_destroy](capi-shared-mutex-h.md#ffrt_rwlock_destroy)销毁。 |
| 49 | 49 | ||
| 50 | **起始版本：** 18 | 50 | **起始版本：** 18 |
| 51 | 51 | ||
| @@ -53,14 +53,14 @@ FFRT_C_API int ffrt_rwlock_init(ffrt_rwlock_t* rwlock, const ffrt_rwlockattr_t* | |||
| 53 | 53 | ||
| 54 | | 参数项 | 描述 | | 54 | | 参数项 | 描述 | |
| 55 | | -- | -- | | 55 | | -- | -- | |
| 56 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | rwlock指针。 | | 56 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | 指向rwlock的指针。 | |
| 57 | -| [const ffrt_rwlockattr_t](capi-ffrt-ffrt-rwlockattr-t.md)* attr | rwlock属性指针，仅支持默认，即设定为空指针。 | | 57 | +| [const ffrt_rwlockattr_t](capi-ffrt-ffrt-rwlockattr-t.md)* attr | 指向rwlock属性的指针。当前仅支持默认模式，需设置为空指针。 | |
| 58 | 58 | ||
| 59 | **返回：** | 59 | **返回：** |
| 60 | 60 | ||
| 61 | | 类型 | 说明 | | 61 | | 类型 | 说明 | |
| 62 | | -- | -- | | 62 | | -- | -- | |
| 63 | -| FFRT_C_API int | `rwlock`不为空，且`attr`为空则初始化成功，返回ffrt_success，<br> 反之初始化rwlock失败，返回ffrt_error_inval。 | | 63 | +| FFRT_C_API int | rwlock初始化成功且attr为空指针时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 64 | 64 | ||
| 65 | ### ffrt_rwlock_wrlock() | 65 | ### ffrt_rwlock_wrlock() |
| 66 | 66 | ||
| @@ -70,7 +70,7 @@ FFRT_C_API int ffrt_rwlock_wrlock(ffrt_rwlock_t* rwlock) | |||
| 70 | 70 | ||
| 71 | **描述** | 71 | **描述** |
| 72 | 72 | ||
| 73 | -获取写锁。 | 73 | +加写锁。锁不可用时阻塞当前线程。成功时，调用线程持有排他写锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。写锁具有排他性，不允许与任何读锁同时持有。 |
| 74 | 74 | ||
| 75 | **起始版本：** 18 | 75 | **起始版本：** 18 |
| 76 | 76 | ||
| @@ -78,13 +78,20 @@ FFRT_C_API int ffrt_rwlock_wrlock(ffrt_rwlock_t* rwlock) | |||
| 78 | 78 | ||
| 79 | | 参数项 | 描述 | | 79 | | 参数项 | 描述 | |
| 80 | | -- | -- | | 80 | | -- | -- | |
| 81 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | rwlock指针。 | | 81 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | 指向rwlock的指针。 | |
| 82 | 82 | ||
| 83 | **返回：** | 83 | **返回：** |
| 84 | 84 | ||
| 85 | | 类型 | 说明 | | 85 | | 类型 | 说明 | |
| 86 | | -- | -- | | 86 | | -- | -- | |
| 87 | -| FFRT_C_API int | 获取写锁成功返回ffrt_success，<br> 获取写锁失败返回ffrt_error_inval或者阻塞当前任务。 | | 87 | +| FFRT_C_API int | rwlock加锁成功时返回`ffrt_success`；<br> `rwlock`为空指针时返回`ffrt_error_inval`。 | |
| 88 | + | ||
| 89 | +**参考：** | ||
| 90 | + | ||
| 91 | +[ffrt_rwlock_rdlock](capi-shared-mutex-h.md#ffrt_rwlock_rdlock) | ||
| 92 | + | ||
| 93 | +[ffrt_rwlock_trywrlock](capi-shared-mutex-h.md#ffrt_rwlock_trywrlock) | ||
| 94 | + | ||
| 88 | 95 | ||
| 89 | ### ffrt_rwlock_trywrlock() | 96 | ### ffrt_rwlock_trywrlock() |
| 90 | 97 | ||
| @@ -94,7 +101,7 @@ FFRT_C_API int ffrt_rwlock_trywrlock(ffrt_rwlock_t* rwlock) | |||
| 94 | 101 | ||
| 95 | **描述** | 102 | **描述** |
| 96 | 103 | ||
| 97 | -尝试获取写锁。 | 104 | +尝试加写锁。不会阻塞当前线程。成功时，调用线程持有排他写锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。 |
| 98 | 105 | ||
| 99 | **起始版本：** 18 | 106 | **起始版本：** 18 |
| 100 | 107 | ||
| @@ -102,13 +109,18 @@ FFRT_C_API int ffrt_rwlock_trywrlock(ffrt_rwlock_t* rwlock) | |||
| 102 | 109 | ||
| 103 | | 参数项 | 描述 | | 110 | | 参数项 | 描述 | |
| 104 | | -- | -- | | 111 | | -- | -- | |
| 105 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | rwlock指针。 | | 112 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | 指向rwlock的指针。 | |
| 106 | 113 | ||
| 107 | **返回：** | 114 | **返回：** |
| 108 | 115 | ||
| 109 | | 类型 | 说明 | | 116 | | 类型 | 说明 | |
| 110 | | -- | -- | | 117 | | -- | -- | |
| 111 | -| FFRT_C_API int | 获取写锁成功返回ffrt_success，<br> 获取写锁失败返回ffrt_error_inval或ffrt_error_busy。 | | 118 | +| FFRT_C_API int | rwlock加锁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`或`ffrt_error_busy`。 | |
| 119 | + | ||
| 120 | +**参考：** | ||
| 121 | + | ||
| 122 | +[ffrt_rwlock_wrlock](capi-shared-mutex-h.md#ffrt_rwlock_wrlock) | ||
| 123 | + | ||
| 112 | 124 | ||
| 113 | ### ffrt_rwlock_rdlock() | 125 | ### ffrt_rwlock_rdlock() |
| 114 | 126 | ||
| @@ -118,7 +130,7 @@ FFRT_C_API int ffrt_rwlock_rdlock(ffrt_rwlock_t* rwlock) | |||
| 118 | 130 | ||
| 119 | **描述** | 131 | **描述** |
| 120 | 132 | ||
| 121 | -获取读锁。 | 133 | +加读锁。锁不可用时阻塞当前线程。成功时，调用线程持有读锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。多个读者可同时持有该锁，但不允许与写锁同时持有。 |
| 122 | 134 | ||
| 123 | **起始版本：** 18 | 135 | **起始版本：** 18 |
| 124 | 136 | ||
| @@ -126,13 +138,20 @@ FFRT_C_API int ffrt_rwlock_rdlock(ffrt_rwlock_t* rwlock) | |||
| 126 | 138 | ||
| 127 | | 参数项 | 描述 | | 139 | | 参数项 | 描述 | |
| 128 | | -- | -- | | 140 | | -- | -- | |
| 129 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | rwlock指针。 | | 141 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | 指向rwlock的指针。 | |
| 130 | 142 | ||
| 131 | **返回：** | 143 | **返回：** |
| 132 | 144 | ||
| 133 | | 类型 | 说明 | | 145 | | 类型 | 说明 | |
| 134 | | -- | -- | | 146 | | -- | -- | |
| 135 | -| FFRT_C_API int | 获取读锁成功返回ffrt_success，<br> 获取读锁失败返回ffrt_error_inval或者阻塞当前任务。 | | 147 | +| FFRT_C_API int | rwlock加锁成功时返回`ffrt_success`；<br> `rwlock`为空指针时返回`ffrt_error_inval`。 | |
| 148 | + | ||
| 149 | +**参考：** | ||
| 150 | + | ||
| 151 | +[ffrt_rwlock_wrlock](capi-shared-mutex-h.md#ffrt_rwlock_wrlock) | ||
| 152 | + | ||
| 153 | +[ffrt_rwlock_tryrdlock](capi-shared-mutex-h.md#ffrt_rwlock_tryrdlock) | ||
| 154 | + | ||
| 136 | 155 | ||
| 137 | ### ffrt_rwlock_tryrdlock() | 156 | ### ffrt_rwlock_tryrdlock() |
| 138 | 157 | ||
| @@ -142,7 +161,7 @@ FFRT_C_API int ffrt_rwlock_tryrdlock(ffrt_rwlock_t* rwlock) | |||
| 142 | 161 | ||
| 143 | **描述** | 162 | **描述** |
| 144 | 163 | ||
| 145 | -尝试获取读锁。 | 164 | +尝试加读锁。不会阻塞当前线程。成功时，调用线程持有读锁，直至通过[ffrt_rwlock_unlock](capi-shared-mutex-h.md#ffrt_rwlock_unlock)释放。 |
| 146 | 165 | ||
| 147 | **起始版本：** 18 | 166 | **起始版本：** 18 |
| 148 | 167 | ||
| @@ -150,13 +169,18 @@ FFRT_C_API int ffrt_rwlock_tryrdlock(ffrt_rwlock_t* rwlock) | |||
| 150 | 169 | ||
| 151 | | 参数项 | 描述 | | 170 | | 参数项 | 描述 | |
| 152 | | -- | -- | | 171 | | -- | -- | |
| 153 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | rwlock指针。 | | 172 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | 指向rwlock的指针。 | |
| 154 | 173 | ||
| 155 | **返回：** | 174 | **返回：** |
| 156 | 175 | ||
| 157 | | 类型 | 说明 | | 176 | | 类型 | 说明 | |
| 158 | | -- | -- | | 177 | | -- | -- | |
| 159 | -| FFRT_C_API int | 获取读锁成功返回ffrt_success，<br> 获取读锁失败返回ffrt_error_inval或ffrt_error_busy。 | | 178 | +| FFRT_C_API int | rwlock加锁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`或`ffrt_error_busy`。 | |
| 179 | + | ||
| 180 | +**参考：** | ||
| 181 | + | ||
| 182 | +[ffrt_rwlock_rdlock](capi-shared-mutex-h.md#ffrt_rwlock_rdlock) | ||
| 183 | + | ||
| 160 | 184 | ||
| 161 | ### ffrt_rwlock_unlock() | 185 | ### ffrt_rwlock_unlock() |
| 162 | 186 | ||
| @@ -166,7 +190,7 @@ FFRT_C_API int ffrt_rwlock_unlock(ffrt_rwlock_t* rwlock) | |||
| 166 | 190 | ||
| 167 | **描述** | 191 | **描述** |
| 168 | 192 | ||
| 169 | -释放rwlock。 | 193 | +解锁rwlock。调用线程必须已持有该rwlock，且该锁之前由[ffrt_rwlock_rdlock](capi-shared-mutex-h.md#ffrt_rwlock_rdlock)、[ffrt_rwlock_tryrdlock](capi-shared-mutex-h.md#ffrt_rwlock_tryrdlock)、[ffrt_rwlock_wrlock](capi-shared-mutex-h.md#ffrt_rwlock_wrlock)或[ffrt_rwlock_trywrlock](capi-shared-mutex-h.md#ffrt_rwlock_trywrlock)获取。 |
| 170 | 194 | ||
| 171 | **起始版本：** 18 | 195 | **起始版本：** 18 |
| 172 | 196 | ||
| @@ -174,13 +198,13 @@ FFRT_C_API int ffrt_rwlock_unlock(ffrt_rwlock_t* rwlock) | |||
| 174 | 198 | ||
| 175 | | 参数项 | 描述 | | 199 | | 参数项 | 描述 | |
| 176 | | -- | -- | | 200 | | -- | -- | |
| 177 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | rwlock指针。 | | 201 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | 指向rwlock的指针。 | |
| 178 | 202 | ||
| 179 | **返回：** | 203 | **返回：** |
| 180 | 204 | ||
| 181 | | 类型 | 说明 | | 205 | | 类型 | 说明 | |
| 182 | | -- | -- | | 206 | | -- | -- | |
| 183 | -| FFRT_C_API int | 释放rwlock成功返回ffrt_success，<br> 释放rwlock失败返回ffrt_error_inval。 | | 207 | +| FFRT_C_API int | rwlock解锁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 184 | 208 | ||
| 185 | ### ffrt_rwlock_destroy() | 209 | ### ffrt_rwlock_destroy() |
| 186 | 210 | ||
| @@ -190,7 +214,7 @@ FFRT_C_API int ffrt_rwlock_destroy(ffrt_rwlock_t* rwlock) | |||
| 190 | 214 | ||
| 191 | **描述** | 215 | **描述** |
| 192 | 216 | ||
| 193 | -销毁rwlock。 | 217 | +销毁rwlock。该rwlock必须已通过[ffrt_rwlock_init](capi-shared-mutex-h.md#ffrt_rwlock_init)初始化，且在调用本接口时不得被任何线程以读锁或写锁持有。 |
| 194 | 218 | ||
| 195 | **起始版本：** 18 | 219 | **起始版本：** 18 |
| 196 | 220 | ||
| @@ -198,12 +222,12 @@ FFRT_C_API int ffrt_rwlock_destroy(ffrt_rwlock_t* rwlock) | |||
| 198 | 222 | ||
| 199 | | 参数项 | 描述 | | 223 | | 参数项 | 描述 | |
| 200 | | -- | -- | | 224 | | -- | -- | |
| 201 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | rwlock指针。 | | 225 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md)* rwlock | 指向rwlock的指针。 | |
| 202 | 226 | ||
| 203 | **返回：** | 227 | **返回：** |
| 204 | 228 | ||
| 205 | | 类型 | 说明 | | 229 | | 类型 | 说明 | |
| 206 | | -- | -- | | 230 | | -- | -- | |
| 207 | -| FFRT_C_API int | 销毁rwlock成功返回ffrt_success，<br>销毁rwlock失败返回ffrt_error_inval。 | | 231 | +| FFRT_C_API int | rwlock销毁成功时返回`ffrt_success`；<br> 否则返回`ffrt_error_inval`。 | |
| 208 | 232 | ||
| 209 | 233 | ||
| @@ -2,14 +2,14 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| 11 | 11 | ||
| 12 | -声明sleep和yield的C接口。 | 12 | +声明[ffrt_usleep](capi-sleep-h.md#ffrt_usleep)和[ffrt_yield](capi-sleep-h.md#ffrt_yield)的C接口。 |
| 13 | 13 | ||
| 14 | **引用文件：** <ffrt/sleep.h> | 14 | **引用文件：** <ffrt/sleep.h> |
| 15 | 15 | ||
| @@ -27,8 +27,8 @@ | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [FFRT_C_API int ffrt_usleep(uint64_t usec)](#ffrt_usleep) | 睡眠调用线程固定的时间。 | | 30 | +| [FFRT_C_API int ffrt_usleep(uint64_t usec)](#ffrt_usleep) | 将调用线程挂起指定的时长。若`usec`超过支持的最大值则按最大值截断。 | |
| 31 | -| [FFRT_C_API void ffrt_yield(void)](#ffrt_yield) | 当前任务主动放权，让其他任务有机会调度执行。 | | 31 | +| [FFRT_C_API void ffrt_yield(void)](#ffrt_yield) | 将控制权让出给其他任务，使其有机会被执行。 | |
| 32 | 32 | ||
| 33 | ## 函数说明 | 33 | ## 函数说明 |
| 34 | 34 | ||
| @@ -40,7 +40,7 @@ FFRT_C_API int ffrt_usleep(uint64_t usec) | |||
| 40 | 40 | ||
| 41 | **描述** | 41 | **描述** |
| 42 | 42 | ||
| 43 | -睡眠调用线程固定的时间。 | 43 | +将调用线程挂起指定的时长。若`usec`超过支持的最大值则按最大值截断。 |
| 44 | 44 | ||
| 45 | **起始版本：** 10 | 45 | **起始版本：** 10 |
| 46 | 46 | ||
| @@ -48,13 +48,13 @@ FFRT_C_API int ffrt_usleep(uint64_t usec) | |||
| 48 | 48 | ||
| 49 | | 参数项 | 描述 | | 49 | | 参数项 | 描述 | |
| 50 | | -- | -- | | 50 | | -- | -- | |
| 51 | -| uint64_t usec | 睡眠时间，单位是微秒。 | | 51 | +| uint64_t usec | 调用线程被挂起的时长，单位是微秒。 | |
| 52 | 52 | ||
| 53 | **返回：** | 53 | **返回：** |
| 54 | 54 | ||
| 55 | | 类型 | 说明 | | 55 | | 类型 | 说明 | |
| 56 | | -- | -- | | 56 | | -- | -- | |
| 57 | -| FFRT_C_API int | 执行成功时返回ffrt_success，<br> 执行失败时返回ffrt_error。 | | 57 | +| FFRT_C_API int | `ffrt_success`。该函数不会失败。 | |
| 58 | 58 | ||
| 59 | ### ffrt_yield() | 59 | ### ffrt_yield() |
| 60 | 60 | ||
| @@ -64,7 +64,7 @@ FFRT_C_API void ffrt_yield(void) | |||
| 64 | 64 | ||
| 65 | **描述** | 65 | **描述** |
| 66 | 66 | ||
| 67 | -当前任务主动放权，让其他任务有机会调度执行。 | 67 | +将控制权让出给其他任务，使其有机会被执行。 |
| 68 | 68 | ||
| 69 | **起始版本：** 10 | 69 | **起始版本：** 10 |
| 70 | 70 | ||
| @@ -2,14 +2,14 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| 11 | 11 | ||
| 12 | -声明任务的C接口。 | 12 | +声明FFRT任务的C接口，提供任务属性的初始化与销毁、任务QoS设置与获取、任务延迟时间管理、并发队列任务优先级管理、任务栈大小管理、任务提交调度执行、任务句柄引用计数管理以及任务等待等功能。 |
| 13 | 13 | ||
| 14 | **引用文件：** <ffrt/task.h> | 14 | **引用文件：** <ffrt/task.h> |
| 15 | 15 | ||
| @@ -27,31 +27,31 @@ | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr)](#ffrt_task_attr_init) | 初始化任务属性。 | | 30 | +| [FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr)](#ffrt_task_attr_init) | 初始化任务属性。调用成功后，任务属性将被设置为默认值（如默认QoS为[ffrt_qos_default](capi-type-def-h.md#ffrt_qos_default_t)）。使用完毕后须调用[ffrt_task_attr_destroy](capi-task-h.md#ffrt_task_attr_destroy)释放任务属性。 | |
| 31 | -| [FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name)](#ffrt_task_attr_set_name) | 设置任务名字。 | | 31 | +| [FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name)](#ffrt_task_attr_set_name) | 设置任务属性的名称。 | |
| 32 | -| [FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_name) | 获取任务名字。 | | 32 | +| [FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_name) | 获取任务属性的名称。 | |
| 33 | -| [FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr)](#ffrt_task_attr_destroy) | 销毁任务属性。 | | 33 | +| [FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr)](#ffrt_task_attr_destroy) | 销毁任务属性。必须在已通过[ffrt_task_attr_init](capi-task-h.md#ffrt_task_attr_init)初始化的任务属性上调用本接口，用于释放属性持有的资源。销毁后该任务属性不可再使用。 | |
| 34 | -| [FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos)](#ffrt_task_attr_set_qos) | 设置任务QoS。 | | 34 | +| [FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos)](#ffrt_task_attr_set_qos) | 设置任务属性的QoS。QoS用于控制任务的调度优先级。例如，对用户交互型任务配置高QoS以保证响应速度，对后台或维护型任务配置低QoS以减少其对系统资源的占用。 | |
| 35 | -| [FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_qos) | 获取任务QoS。 | | 35 | +| [FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_qos) | 获取任务属性的QoS。 | |
| 36 | -| [FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us)](#ffrt_task_attr_set_delay) | 设置任务延迟时间。<br> 设置任务的调度延迟后，任务的输入输出依赖关系不再生效。 | | 36 | +| [FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us)](#ffrt_task_attr_set_delay) | 设置任务属性的延迟时间。 | |
| 37 | -| [FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_delay) | 获取任务延迟时间。 | | 37 | +| [FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_delay) | 获取任务属性的延迟时间。 | |
| 38 | -| [FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority)](#ffrt_task_attr_set_queue_priority) | 设置并行队列任务优先级。 | | 38 | +| [FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority)](#ffrt_task_attr_set_queue_priority) | 设置任务属性的优先级。 | |
| 39 | -| [FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_queue_priority) | 获取并行队列任务优先级。 | | 39 | +| [FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_queue_priority) | 获取任务属性的优先级。 | |
| 40 | -| [FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size)](#ffrt_task_attr_set_stack_size) | 设置任务栈大小。 | | 40 | +| [FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size)](#ffrt_task_attr_set_stack_size) | 设置任务属性的栈大小。 | |
| 41 | -| [FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_stack_size) | 获取任务栈大小。 | | 41 | +| [FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_stack_size) | 获取任务属性的栈大小。 | |
| 42 | -| [FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos)](#ffrt_this_task_update_qos) | 更新任务QoS。 | | 42 | +| [FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos)](#ffrt_this_task_update_qos) | 更新当前任务的QoS。在任务执行过程中需要根据运行阶段动态调整调度优先级时使用本接口。例如，一个后台同步任务在用户触发相关操作后，可通过本接口提升QoS等级以加快处理速度。 | |
| 43 | -| [FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void)](#ffrt_this_task_get_qos) | 获取任务QoS。 | | 43 | +| [FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void)](#ffrt_this_task_get_qos) | 获取当前任务的QoS。 | |
| 44 | -| [FFRT_C_API uint64_t ffrt_this_task_get_id(void)](#ffrt_this_task_get_id) | 获取任务id。 | | 44 | +| [FFRT_C_API uint64_t ffrt_this_task_get_id(void)](#ffrt_this_task_get_id) | 获取当前任务的ID。 | |
| 45 | -| [FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind)](#ffrt_alloc_auto_managed_function_storage_base) | 申请函数执行结构的内存。 | | 45 | +| [FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind)](#ffrt_alloc_auto_managed_function_storage_base) | 申请函数执行结构体的内存。申请的内存用作任务执行体封装，在通过[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)或[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)提交任务时传入。该内存在所提交任务执行完成后由FFRT运行时自动释放，调用方无需手动释放。 | |
| 46 | -| [FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_base) | 提交任务调度执行。 | | 46 | +| [FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_base) | 提交任务调度执行。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系和任务QoS确定任务的执行时机并选择工作线程执行该任务。本接口为底层提交接口，若任务不需要销毁回调，可使用简化接口[ffrt_submit_f](capi-task-h.md#ffrt_submit_f)。与[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)的区别在于本接口不返回任务句柄，适用于不需要对已提交任务进行后续依赖管理或等待的场景。若任务属性中已通过[ffrt_task_attr_set_delay](capi-task-h.md#ffrt_task_attr_set_delay)设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。 | |
| 47 | -| [FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_h_base) | 提交任务调度执行并返回任务句柄。 | | 47 | +| [FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_h_base) | 提交任务调度执行并返回任务句柄。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系确定任务的执行时机。返回的任务句柄可用于通过[ffrt_wait_deps](capi-task-h.md#ffrt_wait_deps)等待任务完成，或作为其他任务的输入依赖以构建任务间的依赖关系。本接口为返回任务句柄的底层提交接口，若任务不需要销毁回调，可使用简化接口[ffrt_submit_h_f](capi-task-h.md#ffrt_submit_h_f)。返回的任务句柄需通过[ffrt_task_handle_destroy](capi-task-h.md#ffrt_task_handle_destroy)销毁，引用计数可通过[ffrt_task_handle_inc_ref](capi-task-h.md#ffrt_task_handle_inc_ref)和[ffrt_task_handle_dec_ref](capi-task-h.md#ffrt_task_handle_dec_ref)管理。 | |
| 48 | -| [FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_f) | 提交任务调度执行，是ffrt_submit_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_base接口。 | | 48 | +| [FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_f) | 提交任务调度执行，是[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（`ffrt_function_kind_general`），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)接口提交。若任务属性中已通过[ffrt_task_attr_set_delay](capi-task-h.md#ffrt_task_attr_set_delay)设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。 | |
| 49 | -| [FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_h_f) | 提交任务调度执行并返回任务句柄，是ffrt_submit_h_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_h_base接口。 | | 49 | +| [FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_h_f) | 提交任务调度执行并返回任务句柄，是[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（`ffrt_function_kind_general`），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)接口提交。若任务属性中已通过[ffrt_task_attr_set_delay](capi-task-h.md#ffrt_task_attr_set_delay)设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。返回的任务句柄需通过[ffrt_task_handle_destroy](capi-task-h.md#ffrt_task_handle_destroy)销毁。 | |
| 50 | -| [FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_inc_ref) | 增加任务句柄的引用数。 | | 50 | +| [FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_inc_ref) | 增加任务句柄的引用计数。任务句柄的引用计数加一，并返回增加前的引用计数值。 | |
| 51 | -| [FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_dec_ref) | 减少任务句柄的引用计数。 | | 51 | +| [FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_dec_ref) | 减少任务句柄的引用计数。任务句柄的引用计数减一，并返回减少前的引用计数值。本接口应与[ffrt_task_handle_inc_ref](capi-task-h.md#ffrt_task_handle_inc_ref)配对使用，句柄不再使用时需通过[ffrt_task_handle_destroy](capi-task-h.md#ffrt_task_handle_destroy)销毁。 | |
| 52 | -| [FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle)](#ffrt_task_handle_destroy) | 销毁任务句柄。 | | 52 | +| [FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle)](#ffrt_task_handle_destroy) | 销毁任务句柄。调用后，任务句柄被销毁并释放关联的资源，句柄不可再使用。 | |
| 53 | -| [FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps)](#ffrt_wait_deps) | 等待依赖的任务完成，当前任务开始执行。 | | 53 | +| [FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps)](#ffrt_wait_deps) | 阻塞当前任务，等待依赖任务完成后再继续执行。 | |
| 54 | -| [FFRT_C_API void ffrt_wait(void)](#ffrt_wait) | 等待之前所有提交任务完成，当前任务开始执行。 | | 54 | +| [FFRT_C_API void ffrt_wait(void)](#ffrt_wait) | 阻塞当前任务，等待所有已提交任务完成后再继续执行。 | |
| 55 | 55 | ||
| 56 | ## 函数说明 | 56 | ## 函数说明 |
| 57 | 57 | ||
| @@ -63,7 +63,7 @@ FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr) | |||
| 63 | 63 | ||
| 64 | **描述** | 64 | **描述** |
| 65 | 65 | ||
| 66 | -初始化任务属性。 | 66 | +初始化任务属性。调用成功后，任务属性将被设置为默认值（如默认QoS为[ffrt_qos_default](capi-type-def-h.md#ffrt_qos_default_t)）。使用完毕后须调用[ffrt_task_attr_destroy](capi-task-h.md#ffrt_task_attr_destroy)释放任务属性。 |
| 67 | 67 | ||
| 68 | **起始版本：** 10 | 68 | **起始版本：** 10 |
| 69 | 69 | ||
| @@ -71,13 +71,13 @@ FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr) | |||
| 71 | 71 | ||
| 72 | | 参数项 | 描述 | | 72 | | 参数项 | 描述 | |
| 73 | | -- | -- | | 73 | | -- | -- | |
| 74 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 74 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 75 | 75 | ||
| 76 | **返回：** | 76 | **返回：** |
| 77 | 77 | ||
| 78 | | 类型 | 说明 | | 78 | | 类型 | 说明 | |
| 79 | | -- | -- | | 79 | | -- | -- | |
| 80 | -| FFRT_C_API int | 初始化任务属性成功返回0，<br> 初始化任务属性失败返回-1。 | | 80 | +| FFRT_C_API int | 任务属性初始化成功时返回`0`；<br> 否则返回`-1`。 | |
| 81 | 81 | ||
| 82 | ### ffrt_task_attr_set_name() | 82 | ### ffrt_task_attr_set_name() |
| 83 | 83 | ||
| @@ -87,7 +87,7 @@ FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name | |||
| 87 | 87 | ||
| 88 | **描述** | 88 | **描述** |
| 89 | 89 | ||
| 90 | -设置任务名字。 | 90 | +设置任务属性的名称。 |
| 91 | 91 | ||
| 92 | **起始版本：** 10 | 92 | **起始版本：** 10 |
| 93 | 93 | ||
| @@ -95,8 +95,8 @@ FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name | |||
| 95 | 95 | ||
| 96 | | 参数项 | 描述 | | 96 | | 参数项 | 描述 | |
| 97 | | -- | -- | | 97 | | -- | -- | |
| 98 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 98 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 99 | -| const char* name | 任务名字。 | | 99 | +| const char* name | 指向任务名称的指针。 | |
| 100 | 100 | ||
| 101 | ### ffrt_task_attr_get_name() | 101 | ### ffrt_task_attr_get_name() |
| 102 | 102 | ||
| @@ -106,7 +106,7 @@ FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr) | |||
| 106 | 106 | ||
| 107 | **描述** | 107 | **描述** |
| 108 | 108 | ||
| 109 | -获取任务名字。 | 109 | +获取任务属性的名称。 |
| 110 | 110 | ||
| 111 | **起始版本：** 10 | 111 | **起始版本：** 10 |
| 112 | 112 | ||
| @@ -114,13 +114,13 @@ FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr) | |||
| 114 | 114 | ||
| 115 | | 参数项 | 描述 | | 115 | | 参数项 | 描述 | |
| 116 | | -- | -- | | 116 | | -- | -- | |
| 117 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 117 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 118 | 118 | ||
| 119 | **返回：** | 119 | **返回：** |
| 120 | 120 | ||
| 121 | | 类型 | 说明 | | 121 | | 类型 | 说明 | |
| 122 | | -- | -- | | 122 | | -- | -- | |
| 123 | -| FFRT_C_API const char* | 获取任务名字成功返回非空指针，<br> 获取任务名字失败返回空指针。 | | 123 | +| FFRT_C_API const char* | 任务名称获取成功时返回非空的任务名称指针；<br> 否则返回空指针。 | |
| 124 | 124 | ||
| 125 | ### ffrt_task_attr_destroy() | 125 | ### ffrt_task_attr_destroy() |
| 126 | 126 | ||
| @@ -130,7 +130,7 @@ FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr) | |||
| 130 | 130 | ||
| 131 | **描述** | 131 | **描述** |
| 132 | 132 | ||
| 133 | -销毁任务属性。 | 133 | +销毁任务属性。必须在已通过[ffrt_task_attr_init](capi-task-h.md#ffrt_task_attr_init)初始化的任务属性上调用本接口，用于释放属性持有的资源。销毁后该任务属性不可再使用。 |
| 134 | 134 | ||
| 135 | **起始版本：** 10 | 135 | **起始版本：** 10 |
| 136 | 136 | ||
| @@ -138,7 +138,7 @@ FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr) | |||
| 138 | 138 | ||
| 139 | | 参数项 | 描述 | | 139 | | 参数项 | 描述 | |
| 140 | | -- | -- | | 140 | | -- | -- | |
| 141 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 141 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 142 | 142 | ||
| 143 | ### ffrt_task_attr_set_qos() | 143 | ### ffrt_task_attr_set_qos() |
| 144 | 144 | ||
| @@ -148,7 +148,7 @@ FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos) | |||
| 148 | 148 | ||
| 149 | **描述** | 149 | **描述** |
| 150 | 150 | ||
| 151 | -设置任务QoS。 | 151 | +设置任务属性的QoS。QoS用于控制任务的调度优先级。例如，对用户交互型任务配置高QoS以保证响应速度，对后台或维护型任务配置低QoS以减少其对系统资源的占用。 |
| 152 | 152 | ||
| 153 | **起始版本：** 10 | 153 | **起始版本：** 10 |
| 154 | 154 | ||
| @@ -156,8 +156,8 @@ FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos) | |||
| 156 | 156 | ||
| 157 | | 参数项 | 描述 | | 157 | | 参数项 | 描述 | |
| 158 | | -- | -- | | 158 | | -- | -- | |
| 159 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 159 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 160 | -| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 任务QoS。 | | 160 | +| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 待设置的QoS等级，取值参考[ffrt_qos_t](capi-type-def-h.md#变量)。 | |
| 161 | 161 | ||
| 162 | ### ffrt_task_attr_get_qos() | 162 | ### ffrt_task_attr_get_qos() |
| 163 | 163 | ||
| @@ -167,7 +167,7 @@ FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr) | |||
| 167 | 167 | ||
| 168 | **描述** | 168 | **描述** |
| 169 | 169 | ||
| 170 | -获取任务QoS。 | 170 | +获取任务属性的QoS。 |
| 171 | 171 | ||
| 172 | **起始版本：** 10 | 172 | **起始版本：** 10 |
| 173 | 173 | ||
| @@ -175,13 +175,13 @@ FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr) | |||
| 175 | 175 | ||
| 176 | | 参数项 | 描述 | | 176 | | 参数项 | 描述 | |
| 177 | | -- | -- | | 177 | | -- | -- | |
| 178 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 178 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 179 | 179 | ||
| 180 | **返回：** | 180 | **返回：** |
| 181 | 181 | ||
| 182 | | 类型 | 说明 | | 182 | | 类型 | 说明 | |
| 183 | | -- | -- | | 183 | | -- | -- | |
| 184 | -| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | 返回任务的QoS，默认返回ffrt_qos_default。 | | 184 | +| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | QoS等级，默认返回`ffrt_qos_default`。 | |
| 185 | 185 | ||
| 186 | ### ffrt_task_attr_set_delay() | 186 | ### ffrt_task_attr_set_delay() |
| 187 | 187 | ||
| @@ -191,9 +191,7 @@ FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_ | |||
| 191 | 191 | ||
| 192 | **描述** | 192 | **描述** |
| 193 | 193 | ||
| 194 | -设置任务延迟时间。 | 194 | +设置任务属性的延迟时间。 |
| 195 | - | ||
| 196 | -设置任务的调度延迟后，任务的输入输出依赖关系不再生效。 | ||
| 197 | 195 | ||
| 198 | **起始版本：** 10 | 196 | **起始版本：** 10 |
| 199 | 197 | ||
| @@ -201,8 +199,8 @@ FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_ | |||
| 201 | 199 | ||
| 202 | | 参数项 | 描述 | | 200 | | 参数项 | 描述 | |
| 203 | | -- | -- | | 201 | | -- | -- | |
| 204 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 202 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 205 | -| uint64_t delay_us | 任务延迟时间，单位微秒。 | | 203 | +| uint64_t delay_us | 任务延迟时间，单位是微秒。 | |
| 206 | 204 | ||
| 207 | ### ffrt_task_attr_get_delay() | 205 | ### ffrt_task_attr_get_delay() |
| 208 | 206 | ||
| @@ -212,7 +210,7 @@ FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr) | |||
| 212 | 210 | ||
| 213 | **描述** | 211 | **描述** |
| 214 | 212 | ||
| 215 | -获取任务延迟时间。 | 213 | +获取任务属性的延迟时间。 |
| 216 | 214 | ||
| 217 | **起始版本：** 10 | 215 | **起始版本：** 10 |
| 218 | 216 | ||
| @@ -220,13 +218,13 @@ FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr) | |||
| 220 | 218 | ||
| 221 | | 参数项 | 描述 | | 219 | | 参数项 | 描述 | |
| 222 | | -- | -- | | 220 | | -- | -- | |
| 223 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 221 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 224 | 222 | ||
| 225 | **返回：** | 223 | **返回：** |
| 226 | 224 | ||
| 227 | | 类型 | 说明 | | 225 | | 类型 | 说明 | |
| 228 | | -- | -- | | 226 | | -- | -- | |
| 229 | -| FFRT_C_API uint64_t | 返回任务的延迟时间。 | | 227 | +| FFRT_C_API uint64_t | 任务延迟时间，单位是微秒。 | |
| 230 | 228 | ||
| 231 | ### ffrt_task_attr_set_queue_priority() | 229 | ### ffrt_task_attr_set_queue_priority() |
| 232 | 230 | ||
| @@ -236,7 +234,7 @@ FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_q | |||
| 236 | 234 | ||
| 237 | **描述** | 235 | **描述** |
| 238 | 236 | ||
| 239 | -设置并行队列任务优先级。 | 237 | +设置任务属性的优先级。 |
| 240 | 238 | ||
| 241 | **起始版本：** 12 | 239 | **起始版本：** 12 |
| 242 | 240 | ||
| @@ -244,8 +242,8 @@ FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_q | |||
| 244 | 242 | ||
| 245 | | 参数项 | 描述 | | 243 | | 参数项 | 描述 | |
| 246 | | -- | -- | | 244 | | -- | -- | |
| 247 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 245 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 248 | -| [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) priority | 任务优先级。 | | 246 | +| [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) priority | 并发队列任务的执行优先级，取值参考[ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t)；在同一并发队列内，高优先级任务优先于低优先级任务被调度。超出合法范围的值会被静默忽略。 | |
| 249 | 247 | ||
| 250 | ### ffrt_task_attr_get_queue_priority() | 248 | ### ffrt_task_attr_get_queue_priority() |
| 251 | 249 | ||
| @@ -255,7 +253,7 @@ FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_ta | |||
| 255 | 253 | ||
| 256 | **描述** | 254 | **描述** |
| 257 | 255 | ||
| 258 | -获取并行队列任务优先级。 | 256 | +获取任务属性的优先级。 |
| 259 | 257 | ||
| 260 | **起始版本：** 12 | 258 | **起始版本：** 12 |
| 261 | 259 | ||
| @@ -263,13 +261,13 @@ FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_ta | |||
| 263 | 261 | ||
| 264 | | 参数项 | 描述 | | 262 | | 参数项 | 描述 | |
| 265 | | -- | -- | | 263 | | -- | -- | |
| 266 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 264 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 267 | 265 | ||
| 268 | **返回：** | 266 | **返回：** |
| 269 | 267 | ||
| 270 | | 类型 | 说明 | | 268 | | 类型 | 说明 | |
| 271 | | -- | -- | | 269 | | -- | -- | |
| 272 | -| FFRT_C_API [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) | 返回任务优先级。 | | 270 | +| FFRT_C_API [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) | 并发队列任务的优先级。 | |
| 273 | 271 | ||
| 274 | ### ffrt_task_attr_set_stack_size() | 272 | ### ffrt_task_attr_set_stack_size() |
| 275 | 273 | ||
| @@ -279,7 +277,7 @@ FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t s | |||
| 279 | 277 | ||
| 280 | **描述** | 278 | **描述** |
| 281 | 279 | ||
| 282 | -设置任务栈大小。 | 280 | +设置任务属性的栈大小。 |
| 283 | 281 | ||
| 284 | **起始版本：** 12 | 282 | **起始版本：** 12 |
| 285 | 283 | ||
| @@ -287,8 +285,8 @@ FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t s | |||
| 287 | 285 | ||
| 288 | | 参数项 | 描述 | | 286 | | 参数项 | 描述 | |
| 289 | | -- | -- | | 287 | | -- | -- | |
| 290 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 288 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 291 | -| uint64_t size | 任务栈大小，单位是字节。 | | 289 | +| uint64_t size | 任务栈大小，单位是字节。需大于系统支持的最小栈大小，否则可能导致栈溢出；<br> 设置过大时可能导致内存分配失败。 | |
| 292 | 290 | ||
| 293 | ### ffrt_task_attr_get_stack_size() | 291 | ### ffrt_task_attr_get_stack_size() |
| 294 | 292 | ||
| @@ -298,7 +296,7 @@ FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr) | |||
| 298 | 296 | ||
| 299 | **描述** | 297 | **描述** |
| 300 | 298 | ||
| 301 | -获取任务栈大小。 | 299 | +获取任务属性的栈大小。 |
| 302 | 300 | ||
| 303 | **起始版本：** 12 | 301 | **起始版本：** 12 |
| 304 | 302 | ||
| @@ -306,13 +304,13 @@ FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr) | |||
| 306 | 304 | ||
| 307 | | 参数项 | 描述 | | 305 | | 参数项 | 描述 | |
| 308 | | -- | -- | | 306 | | -- | -- | |
| 309 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | | 307 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 310 | 308 | ||
| 311 | **返回：** | 309 | **返回：** |
| 312 | 310 | ||
| 313 | | 类型 | 说明 | | 311 | | 类型 | 说明 | |
| 314 | | -- | -- | | 312 | | -- | -- | |
| 315 | -| FFRT_C_API uint64_t | 返回任务栈大小，单位是字节。 | | 313 | +| FFRT_C_API uint64_t | 任务栈大小，单位是字节。 | |
| 316 | 314 | ||
| 317 | ### ffrt_this_task_update_qos() | 315 | ### ffrt_this_task_update_qos() |
| 318 | 316 | ||
| @@ -322,7 +320,7 @@ FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos) | |||
| 322 | 320 | ||
| 323 | **描述** | 321 | **描述** |
| 324 | 322 | ||
| 325 | -更新任务QoS。 | 323 | +更新当前任务的QoS。在任务执行过程中需要根据运行阶段动态调整调度优先级时使用本接口。例如，一个后台同步任务在用户触发相关操作后，可通过本接口提升QoS等级以加快处理速度。 |
| 326 | 324 | ||
| 327 | **起始版本：** 10 | 325 | **起始版本：** 10 |
| 328 | 326 | ||
| @@ -330,13 +328,18 @@ FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos) | |||
| 330 | 328 | ||
| 331 | | 参数项 | 描述 | | 329 | | 参数项 | 描述 | |
| 332 | | -- | -- | | 330 | | -- | -- | |
| 333 | -| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 当前任务待更新的QoS。 | | 331 | +| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 任务待更新的QoS等级，取值参考[ffrt_qos_t](capi-type-def-h.md#变量)。 | |
| 334 | 332 | ||
| 335 | **返回：** | 333 | **返回：** |
| 336 | 334 | ||
| 337 | | 类型 | 说明 | | 335 | | 类型 | 说明 | |
| 338 | | -- | -- | | 336 | | -- | -- | |
| 339 | -| FFRT_C_API int | 更新任务QoS成功返回0，<br> 更新任务QoS失败返回-1。 | | 337 | +| FFRT_C_API int | QoS更新成功，或新QoS与当前QoS相同时返回`0`；<br> QoS映射未注册、当前任务为空，或当前任务非通用类型任务（即非通过[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)或[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)提交的任务）时返回`1`。 | |
‘即非通过’ - 非改成不是，感觉读起来更顺一点？ mazhabandeng 7月13日 评论： 7月13日 评论： | |||
| 338 | + | ||
| 339 | +**参考：** | ||
| 340 | + | ||
| 341 | +[ffrt_this_task_get_qos](capi-task-h.md#ffrt_this_task_get_qos) | ||
| 342 | + | ||
| 340 | 343 | ||
| 341 | ### ffrt_this_task_get_qos() | 344 | ### ffrt_this_task_get_qos() |
| 342 | 345 | ||
| @@ -346,7 +349,7 @@ FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void) | |||
| 346 | 349 | ||
| 347 | **描述** | 350 | **描述** |
| 348 | 351 | ||
| 349 | -获取任务QoS。 | 352 | +获取当前任务的QoS。 |
| 350 | 353 | ||
| 351 | **起始版本：** 12 | 354 | **起始版本：** 12 |
| 352 | 355 | ||
| @@ -354,7 +357,7 @@ FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void) | |||
| 354 | 357 | ||
| 355 | | 类型 | 说明 | | 358 | | 类型 | 说明 | |
| 356 | | -- | -- | | 359 | | -- | -- | |
| 357 | -| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | 返回任务QoS。 | | 360 | +| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | 任务QoS。 | |
| 358 | 361 | ||
| 359 | ### ffrt_this_task_get_id() | 362 | ### ffrt_this_task_get_id() |
| 360 | 363 | ||
| @@ -364,7 +367,7 @@ FFRT_C_API uint64_t ffrt_this_task_get_id(void) | |||
| 364 | 367 | ||
| 365 | **描述** | 368 | **描述** |
| 366 | 369 | ||
| 367 | -获取任务id。 | 370 | +获取当前任务的ID。 |
| 368 | 371 | ||
| 369 | **起始版本：** 10 | 372 | **起始版本：** 10 |
| 370 | 373 | ||
| @@ -372,7 +375,7 @@ FFRT_C_API uint64_t ffrt_this_task_get_id(void) | |||
| 372 | 375 | ||
| 373 | | 类型 | 说明 | | 376 | | 类型 | 说明 | |
| 374 | | -- | -- | | 377 | | -- | -- | |
| 375 | -| FFRT_C_API uint64_t | 返回当前任务的id。 | | 378 | +| FFRT_C_API uint64_t | 当前运行任务的唯一任务ID。 | |
| 376 | 379 | ||
| 377 | ### ffrt_alloc_auto_managed_function_storage_base() | 380 | ### ffrt_alloc_auto_managed_function_storage_base() |
| 378 | 381 | ||
| @@ -382,7 +385,7 @@ FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kin | |||
| 382 | 385 | ||
| 383 | **描述** | 386 | **描述** |
| 384 | 387 | ||
| 385 | -申请函数执行结构的内存。 | 388 | +申请函数执行结构体的内存。申请的内存用作任务执行体封装，在通过[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)或[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)提交任务时传入。该内存在所提交任务执行完成后由FFRT运行时自动释放，调用方无需手动释放。 |
| 386 | 389 | ||
| 387 | **起始版本：** 10 | 390 | **起始版本：** 10 |
| 388 | 391 | ||
| @@ -390,13 +393,20 @@ FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kin | |||
| 390 | 393 | ||
| 391 | | 参数项 | 描述 | | 394 | | 参数项 | 描述 | |
| 392 | | -- | -- | | 395 | | -- | -- | |
| 393 | -| [ffrt_function_kind_t](capi-type-def-h.md#ffrt_function_kind_t) kind | 函数执行结构类型，支持通用和队列函数执行结构类型。 | | 396 | +| [ffrt_function_kind_t](capi-type-def-h.md#ffrt_function_kind_t) kind | 函数执行结构体类型。通用类型适用于通过[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)或[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)提交的任务，<br> 队列类型适用于通过并发队列提交接口提交的任务。 | |
| 394 | 397 | ||
| 395 | **返回：** | 398 | **返回：** |
| 396 | 399 | ||
| 397 | | 类型 | 说明 | | 400 | | 类型 | 说明 | |
| 398 | | -- | -- | | 401 | | -- | -- | |
| 399 | -| FFRT_C_API void * | 申请函数执行结构成功返回非空指针，<br> 申请函数执行结构失败返回空指针。 | | 402 | +| FFRT_C_API void * | 内存申请成功时返回非空指针；<br> 否则返回空指针。 | |
| 403 | + | ||
| 404 | +**参考：** | ||
| 405 | + | ||
| 406 | +[ffrt_submit_base](capi-task-h.md#ffrt_submit_base) | ||
| 407 | + | ||
| 408 | +[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base) | ||
| 409 | + | ||
| 400 | 410 | ||
| 401 | ### ffrt_submit_base() | 411 | ### ffrt_submit_base() |
| 402 | 412 | ||
| @@ -406,7 +416,7 @@ FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* i | |||
| 406 | 416 | ||
| 407 | **描述** | 417 | **描述** |
| 408 | 418 | ||
| 409 | -提交任务调度执行。 | 419 | +提交任务调度执行。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系和任务QoS确定任务的执行时机并选择工作线程执行该任务。本接口为底层提交接口，若任务不需要销毁回调，可使用简化接口[ffrt_submit_f](capi-task-h.md#ffrt_submit_f)。与[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)的区别在于本接口不返回任务句柄，适用于不需要对已提交任务进行后续依赖管理或等待的场景。若任务属性中已通过[ffrt_task_attr_set_delay](capi-task-h.md#ffrt_task_attr_set_delay)设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。 |
| 410 | 420 | ||
| 411 | **起始版本：** 10 | 421 | **起始版本：** 10 |
| 412 | 422 | ||
| @@ -414,10 +424,15 @@ FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* i | |||
| 414 | 424 | ||
| 415 | | 参数项 | 描述 | | 425 | | 参数项 | 描述 | |
| 416 | | -- | -- | | 426 | | -- | -- | |
| 417 | -| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务执行体封装的指针。 | | 427 | +| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务执行体封装的指针，需通过[ffrt_alloc_auto_managed_function_storage_base](capi-task-h.md#ffrt_alloc_auto_managed_function_storage_base)申请内存，且必须包含任务销毁回调函数。 | |
| 418 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | | 428 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 指向输入依赖的指针。 | |
| 419 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | | 429 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 指向输出依赖的指针。 | |
| 420 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 430 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 431 | + | ||
| 432 | +**参考：** | ||
| 433 | + | ||
| 434 | +[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base) | ||
| 435 | + | ||
| 421 | 436 | ||
| 422 | ### ffrt_submit_h_base() | 437 | ### ffrt_submit_h_base() |
| 423 | 438 | ||
| @@ -427,7 +442,7 @@ FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, cons | |||
| 427 | 442 | ||
| 428 | **描述** | 443 | **描述** |
| 429 | 444 | ||
| 430 | -提交任务调度执行并返回任务句柄。 | 445 | +提交任务调度执行并返回任务句柄。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系确定任务的执行时机。返回的任务句柄可用于通过[ffrt_wait_deps](capi-task-h.md#ffrt_wait_deps)等待任务完成，或作为其他任务的输入依赖以构建任务间的依赖关系。本接口为返回任务句柄的底层提交接口，若任务不需要销毁回调，可使用简化接口[ffrt_submit_h_f](capi-task-h.md#ffrt_submit_h_f)。返回的任务句柄需通过[ffrt_task_handle_destroy](capi-task-h.md#ffrt_task_handle_destroy)销毁，引用计数可通过[ffrt_task_handle_inc_ref](capi-task-h.md#ffrt_task_handle_inc_ref)和[ffrt_task_handle_dec_ref](capi-task-h.md#ffrt_task_handle_dec_ref)管理。 |
| 431 | 446 | ||
| 432 | **起始版本：** 10 | 447 | **起始版本：** 10 |
| 433 | 448 | ||
| @@ -435,16 +450,21 @@ FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, cons | |||
| 435 | 450 | ||
| 436 | | 参数项 | 描述 | | 451 | | 参数项 | 描述 | |
| 437 | | -- | -- | | 452 | | -- | -- | |
| 438 | -| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务执行体封装的指针。 | | 453 | +| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务执行体封装的指针，需通过[ffrt_alloc_auto_managed_function_storage_base](capi-task-h.md#ffrt_alloc_auto_managed_function_storage_base)申请内存，且必须包含任务销毁回调函数。 | |
| 439 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | | 454 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 指向输入依赖的指针。 | |
| 440 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | | 455 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 指向输出依赖的指针。 | |
| 441 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 456 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 442 | 457 | ||
| 443 | **返回：** | 458 | **返回：** |
| 444 | 459 | ||
| 445 | | 类型 | 说明 | | 460 | | 类型 | 说明 | |
| 446 | | -- | -- | | 461 | | -- | -- | |
| 447 | -| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交任务成功返回非空任务句柄，<br> 提交任务失败返回空指针。 | | 462 | +| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 任务提交成功时返回非空的任务句柄；<br> 否则返回空指针。 | |
| 463 | + | ||
| 464 | +**参考：** | ||
| 465 | + | ||
| 466 | +[ffrt_submit_base](capi-task-h.md#ffrt_submit_base) | ||
| 467 | + | ||
| 448 | 468 | ||
| 449 | ### ffrt_submit_f() | 469 | ### ffrt_submit_f() |
| 450 | 470 | ||
| @@ -454,7 +474,7 @@ FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t | |||
| 454 | 474 | ||
| 455 | **描述** | 475 | **描述** |
| 456 | 476 | ||
| 457 | -提交任务调度执行，是ffrt_submit_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_base接口。 | 477 | +提交任务调度执行，是[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（`ffrt_function_kind_general`），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过[ffrt_submit_base](capi-task-h.md#ffrt_submit_base)接口提交。若任务属性中已通过[ffrt_task_attr_set_delay](capi-task-h.md#ffrt_task_attr_set_delay)设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。 |
| 458 | 478 | ||
| 459 | **起始版本：** 20 | 479 | **起始版本：** 20 |
| 460 | 480 | ||
| @@ -462,11 +482,11 @@ FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t | |||
| 462 | 482 | ||
| 463 | | 参数项 | 描述 | | 483 | | 参数项 | 描述 | |
| 464 | | -- | -- | | 484 | | -- | -- | |
| 465 | -| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | | 485 | +| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 待执行的任务函数。 | |
| 466 | -| void* arg | 传递给任务函数的参数。 | | 486 | +| void* arg | 指向传递给任务函数的参数或闭包数据的指针。 | |
| 467 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | | 487 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 指向输入依赖的指针。 | |
| 468 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | | 488 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 指向输出依赖的指针。 | |
| 469 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 489 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 470 | 490 | ||
| 471 | **参考：** | 491 | **参考：** |
| 472 | 492 | ||
| @@ -481,7 +501,7 @@ FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, c | |||
| 481 | 501 | ||
| 482 | **描述** | 502 | **描述** |
| 483 | 503 | ||
| 484 | -提交任务调度执行并返回任务句柄，是ffrt_submit_h_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_h_base接口。 | 504 | +提交任务调度执行并返回任务句柄，是[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（`ffrt_function_kind_general`），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)接口提交。若任务属性中已通过[ffrt_task_attr_set_delay](capi-task-h.md#ffrt_task_attr_set_delay)设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。返回的任务句柄需通过[ffrt_task_handle_destroy](capi-task-h.md#ffrt_task_handle_destroy)销毁。 |
| 485 | 505 | ||
| 486 | **起始版本：** 20 | 506 | **起始版本：** 20 |
| 487 | 507 | ||
| @@ -489,17 +509,17 @@ FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, c | |||
| 489 | 509 | ||
| 490 | | 参数项 | 描述 | | 510 | | 参数项 | 描述 | |
| 491 | | -- | -- | | 511 | | -- | -- | |
| 492 | -| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | | 512 | +| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 待执行的任务函数。 | |
| 493 | -| void* arg | 传递给任务函数的参数。 | | 513 | +| void* arg | 指向传递给任务函数的参数或闭包数据的指针。 | |
| 494 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | | 514 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 指向输入依赖的指针。 | |
| 495 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | | 515 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 指向输出依赖的指针。 | |
| 496 | -| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | | 516 | +| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 指向任务属性的指针。 | |
| 497 | 517 | ||
| 498 | **返回：** | 518 | **返回：** |
| 499 | 519 | ||
| 500 | | 类型 | 说明 | | 520 | | 类型 | 说明 | |
| 501 | | -- | -- | | 521 | | -- | -- | |
| 502 | -| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交任务成功返回非空任务句柄，<br> 提交任务失败返回空指针。 | | 522 | +| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 任务提交成功时返回非空的任务句柄；<br> 否则返回空指针。 | |
| 503 | 523 | ||
| 504 | **参考：** | 524 | **参考：** |
| 505 | 525 | ||
| @@ -514,7 +534,7 @@ FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle) | |||
| 514 | 534 | ||
| 515 | **描述** | 535 | **描述** |
| 516 | 536 | ||
| 517 | -增加任务句柄的引用数。 | 537 | +增加任务句柄的引用计数。任务句柄的引用计数加一，并返回增加前的引用计数值。 |
| 518 | 538 | ||
| 519 | **起始版本：** 12 | 539 | **起始版本：** 12 |
| 520 | 540 | ||
| @@ -522,13 +542,13 @@ FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle) | |||
| 522 | 542 | ||
| 523 | | 参数项 | 描述 | | 543 | | 参数项 | 描述 | |
| 524 | | -- | -- | | 544 | | -- | -- | |
| 525 | -| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | 任务句柄。 | | 545 | +| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | 任务句柄，由[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base)或[ffrt_submit_h_f](capi-task-h.md#ffrt_submit_h_f)返回。 | |
| 526 | 546 | ||
| 527 | **返回：** | 547 | **返回：** |
| 528 | 548 | ||
| 529 | | 类型 | 说明 | | 549 | | 类型 | 说明 | |
| 530 | | -- | -- | | 550 | | -- | -- | |
| 531 | -| FFRT_C_API uint32_t | 返回任务句柄原始引用计数。 | | 551 | +| FFRT_C_API uint32_t | 任务句柄增加前的引用计数值；若`handle`为null则返回`UINT_MAX`。 | |
| 532 | 552 | ||
| 533 | ### ffrt_task_handle_dec_ref() | 553 | ### ffrt_task_handle_dec_ref() |
| 534 | 554 | ||
| @@ -538,7 +558,7 @@ FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle) | |||
| 538 | 558 | ||
| 539 | **描述** | 559 | **描述** |
| 540 | 560 | ||
| 541 | -减少任务句柄的引用计数。 | 561 | +减少任务句柄的引用计数。任务句柄的引用计数减一，并返回减少前的引用计数值。本接口应与[ffrt_task_handle_inc_ref](capi-task-h.md#ffrt_task_handle_inc_ref)配对使用，句柄不再使用时需通过[ffrt_task_handle_destroy](capi-task-h.md#ffrt_task_handle_destroy)销毁。 |
| 542 | 562 | ||
| 543 | **起始版本：** 12 | 563 | **起始版本：** 12 |
| 544 | 564 | ||
| @@ -552,7 +572,7 @@ FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle) | |||
| 552 | 572 | ||
| 553 | | 类型 | 说明 | | 573 | | 类型 | 说明 | |
| 554 | | -- | -- | | 574 | | -- | -- | |
| 555 | -| FFRT_C_API uint32_t | 返回任务句柄原始引用计数。 | | 575 | +| FFRT_C_API uint32_t | 任务句柄减少前的引用计数值；若`handle`为null则返回`UINT_MAX`。 | |
| 556 | 576 | ||
| 557 | ### ffrt_task_handle_destroy() | 577 | ### ffrt_task_handle_destroy() |
| 558 | 578 | ||
| @@ -562,7 +582,7 @@ FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle) | |||
| 562 | 582 | ||
| 563 | **描述** | 583 | **描述** |
| 564 | 584 | ||
| 565 | -销毁任务句柄。 | 585 | +销毁任务句柄。调用后，任务句柄被销毁并释放关联的资源，句柄不可再使用。 |
| 566 | 586 | ||
| 567 | **起始版本：** 10 | 587 | **起始版本：** 10 |
| 568 | 588 | ||
| @@ -580,7 +600,7 @@ FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps) | |||
| 580 | 600 | ||
| 581 | **描述** | 601 | **描述** |
| 582 | 602 | ||
| 583 | -等待依赖的任务完成，当前任务开始执行。 | 603 | +阻塞当前任务，等待依赖任务完成后再继续执行。 |
| 584 | 604 | ||
| 585 | **起始版本：** 10 | 605 | **起始版本：** 10 |
| 586 | 606 | ||
| @@ -588,7 +608,7 @@ FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps) | |||
| 588 | 608 | ||
| 589 | | 参数项 | 描述 | | 609 | | 参数项 | 描述 | |
| 590 | | -- | -- | | 610 | | -- | -- | |
| 591 | -| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* deps | 依赖的指针。 | | 611 | +| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* deps | 指向依赖任务列表的指针。阻塞当前任务，直到该依赖列表引用的所有任务执行完毕。 | |
| 592 | 612 | ||
| 593 | ### ffrt_wait() | 613 | ### ffrt_wait() |
| 594 | 614 | ||
| @@ -598,7 +618,7 @@ FFRT_C_API void ffrt_wait(void) | |||
| 598 | 618 | ||
| 599 | **描述** | 619 | **描述** |
| 600 | 620 | ||
| 601 | -等待之前所有提交任务完成，当前任务开始执行。 | 621 | +阻塞当前任务，等待所有已提交任务完成后再继续执行。 |
| 602 | 622 | ||
| 603 | **起始版本：** 10 | 623 | **起始版本：** 10 |
| 604 | 624 | ||
| @@ -2,14 +2,14 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| 11 | 11 | ||
| 12 | -声明定时器的C接口。 | 12 | +声明定时器的C接口。提供基于QoS等级的定时器能力，支持在指定超时时间后执行回调函数，可用于延时任务调度等场景。 |
| 13 | 13 | ||
| 14 | **引用文件：** <ffrt/timer.h> | 14 | **引用文件：** <ffrt/timer.h> |
| 15 | 15 | ||
| @@ -27,8 +27,8 @@ | |||
| 27 | 27 | ||
| 28 | | 名称 | 描述 | | 28 | | 名称 | 描述 | |
| 29 | | -- | -- | | 29 | | -- | -- | |
| 30 | -| [FFRT_C_API ffrt_timer_t ffrt_timer_start(ffrt_qos_t qos, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat)](#ffrt_timer_start) | 启动计时器。 | | 30 | +| [FFRT_C_API ffrt_timer_t ffrt_timer_start(ffrt_qos_t qos, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat)](#ffrt_timer_start) | 在FFRT工作线程上启动定时器。避免在`cb`中调用`exit`或[ffrt_timer_stop](capi-timer-h.md#ffrt_timer_stop)，以防止未定义行为或死锁。 | |
| 31 | -| [FFRT_C_API int ffrt_timer_stop(ffrt_qos_t qos, ffrt_timer_t handle)](#ffrt_timer_stop) | 关闭计时器。 | | 31 | +| [FFRT_C_API int ffrt_timer_stop(ffrt_qos_t qos, ffrt_timer_t handle)](#ffrt_timer_stop) | 停止FFRT工作线程上的定时器。该接口为阻塞接口。请避免在回调函数内调用该接口，以防止死锁或同步问题。当`handle`对应的回调正在执行时，该函数会等待回调完成后再返回。 | |
| 32 | 32 | ||
| 33 | ## 函数说明 | 33 | ## 函数说明 |
| 34 | 34 | ||
| @@ -40,9 +40,7 @@ FFRT_C_API ffrt_timer_t ffrt_timer_start(ffrt_qos_t qos, uint64_t timeout, void* | |||
| 40 | 40 | ||
| 41 | **描述** | 41 | **描述** |
| 42 | 42 | ||
| 43 | -启动计时器。 | 43 | +在FFRT工作线程上启动定时器。避免在`cb`中调用`exit`或[ffrt_timer_stop](capi-timer-h.md#ffrt_timer_stop)，以防止未定义行为或死锁。 |
| 44 | - | ||
| 45 | -不建议在`cb`中调用`exit`函数，可能导致未定义行为。 | ||
| 46 | 44 | ||
| 47 | **起始版本：** 12 | 45 | **起始版本：** 12 |
| 48 | 46 | ||
| @@ -50,17 +48,22 @@ FFRT_C_API ffrt_timer_t ffrt_timer_start(ffrt_qos_t qos, uint64_t timeout, void* | |||
| 50 | 48 | ||
| 51 | | 参数项 | 描述 | | 49 | | 参数项 | 描述 | |
| 52 | | -- | -- | | 50 | | -- | -- | |
| 53 | -| [ffrt_qos_t](capi-type-def-h.md#变量) qos | QoS等级。 | | 51 | +| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 运行定时器的工作线程的QoS等级。 | |
| 54 | -| uint64_t timeout | 超时时间(毫秒)。 | | 52 | +| uint64_t timeout | 超时时间，单位是毫秒。 | |
| 55 | -| void* data | 超时后回调函数的入参。 | | 53 | +| void* data | 传递给`cb`的用户数据。 | |
| 56 | -| [ffrt_timer_cb](capi-type-def-h.md#ffrt_timer_cb) cb | 超时执行的回调函数。 | | 54 | +| [ffrt_timer_cb](capi-type-def-h.md#ffrt_timer_cb) cb | 超时后执行的用户回调函数。 | |
| 57 | -| bool repeat | 是否重复执行该定时器（该功能暂未支持）。 | | 55 | +| bool repeat | 是否重复执行该定时器。`true`表示重复，`false`表示只执行一次。 | |
| 58 | 56 | ||
| 59 | **返回：** | 57 | **返回：** |
| 60 | 58 | ||
| 61 | | 类型 | 说明 | | 59 | | 类型 | 说明 | |
| 62 | | -- | -- | | 60 | | -- | -- | |
| 63 | -| FFRT_C_API [ffrt_timer_t](capi-type-def-h.md#变量) | 返回定时器句柄。 | | 61 | +| FFRT_C_API [ffrt_timer_t](capi-type-def-h.md#变量) | 定时器句柄；若回调函数为空指针或QoS映射未注册则返回`-1`。 | |
| 62 | + | ||
| 63 | +**参考：** | ||
| 64 | + | ||
| 65 | +[ffrt_timer_stop](capi-timer-h.md#ffrt_timer_stop) | ||
| 66 | + | ||
| 64 | 67 | ||
| 65 | ### ffrt_timer_stop() | 68 | ### ffrt_timer_stop() |
| 66 | 69 | ||
| @@ -70,13 +73,7 @@ FFRT_C_API int ffrt_timer_stop(ffrt_qos_t qos, ffrt_timer_t handle) | |||
| 70 | 73 | ||
| 71 | **描述** | 74 | **描述** |
| 72 | 75 | ||
| 73 | -关闭计时器。 | 76 | +停止FFRT工作线程上的定时器。该接口为阻塞接口。请避免在回调函数内调用该接口，以防止死锁或同步问题。当`handle`对应的回调正在执行时，该函数会等待回调完成后再返回。 |
| 74 | - | ||
| 75 | -> **说明：** | ||
| 76 | -> | ||
| 77 | -> 为阻塞接口，请避免在回调函数callback内使用，防止死锁或同步问题。 | ||
| 78 | -> | ||
| 79 | -> 当传入的handle对应的callback正在执行时，该函数会等待callback完成后再继续执行。 | ||
| 80 | 77 | ||
| 81 | **起始版本：** 12 | 78 | **起始版本：** 12 |
| 82 | 79 | ||
| @@ -84,13 +81,18 @@ FFRT_C_API int ffrt_timer_stop(ffrt_qos_t qos, ffrt_timer_t handle) | |||
| 84 | 81 | ||
| 85 | | 参数项 | 描述 | | 82 | | 参数项 | 描述 | |
| 86 | | -- | -- | | 83 | | -- | -- | |
| 87 | -| ffrt_qos_t qos | QoS等级。 | | 84 | +| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 运行定时器的工作线程的QoS等级。必须与[ffrt_timer_start](capi-timer-h.md#ffrt_timer_start)中使用的QoS等级一致。 | |
| 88 | -| ffrt_timer_t handle | 定时器句柄。 | | 85 | +| [ffrt_timer_t](capi-type-def-h.md#变量) handle | 目标定时器句柄，由[ffrt_timer_start](capi-timer-h.md#ffrt_timer_start)返回。 | |
| 89 | 86 | ||
| 90 | **返回：** | 87 | **返回：** |
| 91 | 88 | ||
| 92 | | 类型 | 说明 | | 89 | | 类型 | 说明 | |
| 93 | | -- | -- | | 90 | | -- | -- | |
| 94 | -| FFRT_C_API int | 关闭成功返回0，<br> 关闭失败返回-1。 | | 91 | +| FFRT_C_API int | 操作成功时返回`0`；<br> 否则返回`-1`。 | |
| 92 | + | ||
| 93 | +**参考：** | ||
| 94 | + | ||
| 95 | +[ffrt_timer_start](capi-timer-h.md#ffrt_timer_start) | ||
| 96 | + | ||
| 95 | 97 | ||
| 96 | 98 | ||
| @@ -2,9 +2,9 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Function Flow Runtime Kit--> | 3 | <!--Kit: Function Flow Runtime Kit--> |
| 4 | <!--Subsystem: Resourceschedule--> | 4 | <!--Subsystem: Resourceschedule--> |
| 5 | -<!--Owner: @chuchihtung; @yanleo--> | 5 | +<!--Owner: @chuchihtung--> |
| 6 | -<!--Designer: @geoffrey_guo; @huangyouzhong--> | 6 | +<!--Designer: @zhanglu161--> |
| 7 | -<!--Tester: @lotsof; @sunxuhao--> | 7 | +<!--Tester: @lotsof--> |
| 8 | <!--Adviser: @jinqiuheng--> | 8 | <!--Adviser: @jinqiuheng--> |
| 9 | 9 | ||
| 10 | ## 概述 | 10 | ## 概述 |
| @@ -27,48 +27,48 @@ | |||
| 27 | 27 | ||
| 28 | | 名称 | typedef关键字 | 描述 | | 28 | | 名称 | typedef关键字 | 描述 | |
| 29 | |-----|------------|------------------------| | 29 | |-----|------------|------------------------| |
| 30 | -| int | ffrt_timer_t | 定时器句柄。 | | 30 | +| int | ffrt_qos_t | QoS类型，用于设置任务的Qos等级。 | |
| 31 | -| int | ffrt_qos_t | QoS类型。 | | 31 | +| int | ffrt_timer_t | 定时器句柄，用于标识已创建的定时器。 | |
| 32 | | using qos = int | - | QoS类型。<br>**起始版本：** 10 | | 32 | | using qos = int | - | QoS类型。<br>**起始版本：** 10 | |
| 33 | 33 | ||
| 34 | ### 结构体 | 34 | ### 结构体 |
| 35 | 35 | ||
| 36 | | 名称 | typedef关键字 | 描述 | | 36 | | 名称 | typedef关键字 | 描述 | |
| 37 | | -- | -- | -- | | 37 | | -- | -- | -- | |
| 38 | -| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md) | ffrt_function_header_t | 任务执行体。 | | 38 | +| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md) | ffrt_function_header_t | 任务执行体，用于定义任务的执行和销毁回调。`exec`回调在任务被调度时调用，`destroy`回调在任务完成后被调用以释放任务相关资源。两者共同管理FFRT任务的完整生命周期。 | |
| 39 | -| [ffrt_dependence_t](capi-ffrt-ffrt-dependence-t.md) | ffrt_dependence_t | 依赖数据结构。 | | 39 | +| [ffrt_dependence_t](capi-ffrt-ffrt-dependence-t.md) | ffrt_dependence_t | 依赖数据项结构，用于描述任务间的单个依赖关系。 | |
| 40 | -| [ffrt_deps_t](capi-ffrt-ffrt-deps-t.md) | ffrt_deps_t | 依赖结构定义。 | | 40 | +| [ffrt_deps_t](capi-ffrt-ffrt-deps-t.md) | ffrt_deps_t | 依赖结构体，用于保存任务的依赖列表。 | |
| 41 | -| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md) | ffrt_task_attr_t | 并行任务属性结构。 | | 41 | +| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md) | ffrt_task_attr_t | 任务属性结构体，用于存储任务的属性信息。 | |
| 42 | -| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md) | ffrt_queue_attr_t | 串行队列属性结构。 | | 42 | +| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md) | ffrt_queue_attr_t | 队列属性结构体，用于存储队列的属性信息。 | |
| 43 | -| [ffrt_condattr_t](capi-ffrt-ffrt-condattr-t.md) | ffrt_condattr_t | FFRT条件变量属性结构。 | | 43 | +| [ffrt_condattr_t](capi-ffrt-ffrt-condattr-t.md) | ffrt_condattr_t | 条件变量属性结构体，用于存储条件变量的属性信息。 | |
| 44 | -| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md) | ffrt_mutexattr_t | FFRT锁属性结构。 | | 44 | +| [ffrt_mutexattr_t](capi-ffrt-ffrt-mutexattr-t.md) | ffrt_mutexattr_t | 互斥锁属性结构体，用于存储互斥锁的属性信息。 | |
| 45 | -| [ffrt_rwlockattr_t](capi-ffrt-ffrt-rwlockattr-t.md) | ffrt_rwlockattr_t | FFRT读写锁属性结构。 | | 45 | +| [ffrt_rwlockattr_t](capi-ffrt-ffrt-rwlockattr-t.md) | ffrt_rwlockattr_t | 读写锁属性结构体，用于存储读写锁的属性信息。 | |
| 46 | -| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md) | ffrt_mutex_t | FFRT互斥锁结构。 | | 46 | +| [ffrt_mutex_t](capi-ffrt-ffrt-mutex-t.md) | ffrt_mutex_t | 互斥锁结构体，用于存储互斥锁的内部数据。 | |
| 47 | -| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md) | ffrt_rwlock_t | FFRT读写锁结构。 | | 47 | +| [ffrt_rwlock_t](capi-ffrt-ffrt-rwlock-t.md) | ffrt_rwlock_t | 读写锁结构体，用于存储读写锁的内部数据。 | |
| 48 | -| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md) | ffrt_cond_t | FFRT条件变量结构。 | | 48 | +| [ffrt_cond_t](capi-ffrt-ffrt-cond-t.md) | ffrt_cond_t | 条件变量结构体，用于存储条件变量的内部数据。 | |
| 49 | -| void* | [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 并行任务句柄。 | | 49 | +| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | ffrt_task_handle_t | 任务句柄，用于标识不同的任务。 | |
| 50 | -| [ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md) | ffrt_fiber_t | 纤程结构。 | | 50 | +| [ffrt_fiber_t](capi-ffrt-ffrt-fiber-t.md) | ffrt_fiber_t | 纤程结构体，用于存储纤程执行上下文。 | |
| 51 | 51 | ||
| 52 | ### 枚举 | 52 | ### 枚举 |
| 53 | 53 | ||
| 54 | | 名称 | typedef关键字 | 描述 | | 54 | | 名称 | typedef关键字 | 描述 | |
| 55 | | -- | -- | -- | | 55 | | -- | -- | -- | |
| 56 | -| [ffrt_queue_priority_t](#ffrt_queue_priority_t) | ffrt_queue_priority_t | 任务的优先级类型。 | | 56 | +| [ffrt_queue_priority_t](#ffrt_queue_priority_t) | ffrt_queue_priority_t | 并发队列中用于排序任务调度的任务优先级类型枚举。 | |
| 57 | -| [ffrt_qos_default_t](#ffrt_qos_default_t) | ffrt_qos_default_t | 任务的QoS类型。 | | 57 | +| [ffrt_qos_default_t](#ffrt_qos_default_t) | ffrt_qos_default_t | 任务QoS类型枚举。 | |
| 58 | -| [ffrt_storage_size_t](#ffrt_storage_size_t) | ffrt_storage_size_t | 多种类型数据结构分配大小定义。 | | 58 | +| [ffrt_storage_size_t](#ffrt_storage_size_t) | ffrt_storage_size_t | 多种类型结构体的存储大小定义，单位是字节。 | |
| 59 | -| [ffrt_function_kind_t](#ffrt_function_kind_t) | ffrt_function_kind_t | 任务类型。 | | 59 | +| [ffrt_function_kind_t](#ffrt_function_kind_t) | ffrt_function_kind_t | 任务类型枚举，用于区分通用并发任务和队列调度的任务。 | |
| 60 | -| [ffrt_dependence_type_t](#ffrt_dependence_type_t) | ffrt_dependence_type_t | 依赖类型。 | | 60 | +| [ffrt_dependence_type_t](#ffrt_dependence_type_t) | ffrt_dependence_type_t | 依赖类型枚举。用于指定任务间的依赖关系（数据就绪或任务完成）。 | |
| 61 | -| [ffrt_error_t](#ffrt_error_t) | ffrt_error_t | FFRT错误码。 | | 61 | +| [ffrt_error_t](#ffrt_error_t) | ffrt_error_t | 错误码枚举，由FFRT接口返回。 | |
| 62 | -| [ffrt_mutex_type](#ffrt_mutex_type) | ffrt_mutex_type | 互斥锁类型枚举。描述互斥类型，ffrt_mutex_normal是普通互斥锁；ffrt_mutex_recursive是递归互斥锁，ffrt_mutex_default是普通互斥锁。 | | 62 | +| [ffrt_mutex_type](#ffrt_mutex_type) | ffrt_mutex_type | 互斥锁类型枚举。 | |
| 63 | -| [qos_default](#qos_default) | - | 任务QoS类型枚举。 | | 63 | +| [qos_default](#qos_default) | - | 任务QoS类型枚举。各枚举值与[ffrt_qos_default_t](capi-type-def-h.md#ffrt_qos_default_t)中对应的枚举值等价。 | |
| 64 | 64 | ||
| 65 | ### 函数 | 65 | ### 函数 |
| 66 | 66 | ||
| 67 | | 名称 | typedef关键字 | 描述 | | 67 | | 名称 | typedef关键字 | 描述 | |
| 68 | | -- | -- | -- | | 68 | | -- | -- | -- | |
| 69 | -| [typedef void(\*ffrt_function_t)(void*)](#ffrt_function_t) | ffrt_function_t | 任务执行函数指针类型。 | | 69 | +| [typedef void(\*ffrt_function_t)(void*)](#ffrt_function_t) | ffrt_function_t | 任务执行函数指针类型。函数指针定义了FFRT任务的入口点。FFRT在调度执行任务时调用该函数，并通过参数传入用户数据指针。 | |
| 70 | -| [typedef void (\*ffrt_poller_cb)(void* data, uint32_t event)](#ffrt_poller_cb) | ffrt_poller_cb | poller回调函数定义。 | | 70 | +| [typedef void (\*ffrt_poller_cb)(void* data, uint32_t event)](#ffrt_poller_cb) | ffrt_poller_cb | poller回调函数类型。当poller检测到已注册事件时调用该回调。`data`指针携带注册时传入的用户数据，`event`值标识触发的事件类型。 | |
| 71 | -| [typedef void (\*ffrt_timer_cb)(void* data)](#ffrt_timer_cb) | ffrt_timer_cb | timer回调函数定义。 | | 71 | +| [typedef void (\*ffrt_timer_cb)(void* data)](#ffrt_timer_cb) | ffrt_timer_cb | 定时器回调函数类型。当定时器到期时调用该回调。`data`指针携带定时器注册时传入的用户数据。 | |
| 72 | 72 | ||
| 73 | ## 枚举类型说明 | 73 | ## 枚举类型说明 |
| 74 | 74 | ||
| @@ -80,16 +80,16 @@ enum ffrt_queue_priority_t | |||
| 80 | 80 | ||
| 81 | **描述** | 81 | **描述** |
| 82 | 82 | ||
| 83 | -任务的优先级类型。 | 83 | +并发队列中用于排序任务调度的任务优先级类型枚举。 |
| 84 | 84 | ||
| 85 | **起始版本：** 12 | 85 | **起始版本：** 12 |
| 86 | 86 | ||
| 87 | | 枚举项 | 描述 | | 87 | | 枚举项 | 描述 | |
| 88 | | -- | -- | | 88 | | -- | -- | |
| 89 | -| ffrt_queue_priority_immediate = 0 | immediate 优先级 | | 89 | +| ffrt_queue_priority_immediate = 0 | 最高优先级。任务尽快被调度（句柄时间等于提交时间）；优先于`high`被调度。 | |
| 90 | -| ffrt_queue_priority_high | high 优先级 | | 90 | +| ffrt_queue_priority_high | 高优先级。按句柄时间排序；优先于`low`被调度。 | |
| 91 | -| ffrt_queue_priority_low | low 优先级 | | 91 | +| ffrt_queue_priority_low | 低优先级。按句柄时间排序；优先于`idle`被调度。 | |
| 92 | -| ffrt_queue_priority_idle | lowest 优先级 | | 92 | +| ffrt_queue_priority_idle | 最低优先级。按句柄时间排序；仅在队列中不存在其他优先级任务时才被调度。 | |
| 93 | 93 | ||
| 94 | ### ffrt_qos_default_t | 94 | ### ffrt_qos_default_t |
| 95 | 95 | ||
| @@ -99,138 +99,137 @@ enum ffrt_qos_default_t | |||
| 99 | 99 | ||
| 100 | **描述** | 100 | **描述** |
| 101 | 101 | ||
| 102 | -任务的QoS类型。 | ||
| 103 | - | ||
| 104 | -**起始版本：** 10 | ||
| 105 | - | ||
| 106 | -| 枚举项 | 描述 | | ||
| 107 | -| -- | -- | | ||
| 108 | -| ffrt_qos_inherit = -1 | 继承当前任务QoS属性 | | ||
| 109 | -| ffrt_qos_background | 后台任务 | | ||
| 110 | -| ffrt_qos_utility | 实时工具 | | ||
| 111 | -| ffrt_qos_default | 默认类型 | | ||
| 112 | -| ffrt_qos_user_initiated | 用户期望 | | ||
| 113 | -| ffrt_qos_deadline_request | 时限请求<br>**起始版本：** 23 | | ||
| 114 | -| ffrt_qos_user_interactive | 用户交互<br>**起始版本：** 23 | | ||
| 115 | -| ffrt_qos_max = ffrt_qos_user_interactive | 最高QoS等级<br>**起始版本：** 23 | | ||
| 116 | - | ||
| 117 | -### ffrt_storage_size_t | ||
| 118 | - | ||
| 119 | -```c | ||
| 120 | -enum ffrt_storage_size_t | ||
| 121 | -``` | ||
| 122 | - | ||
| 123 | -**描述** | ||
| 124 | - | ||
| 125 | -多种类型数据结构分配大小定义。 | ||
| 126 | - | ||
| 127 | -**起始版本：** 10 | ||
| 128 | - | ||
| 129 | -| 枚举项 | 描述 | | ||
| 130 | -| -- | -- | | ||
| 131 | -| ffrt_task_attr_storage_size = 128 | 任务属性 | | ||
| 132 | -| ffrt_auto_managed_function_storage_size = 64 + sizeof(ffrt_function_header_t) | 任务执行体 | | ||
| 133 | -| ffrt_mutex_storage_size = 64 | 互斥锁 | | ||
| 134 | -| ffrt_cond_storage_size = 64 | 条件变量 | | ||
| 135 | -| ffrt_queue_attr_storage_size = 128 | 队列属性 | | ||
| 136 | -| ffrt_rwlock_storage_size = 64 | 读写锁<br>**起始版本：** 18 | | ||
| 137 | -| ffrt_fiber_storage_size| 纤程在不同平台所占大小，单位：Byte。（平台相关）aarch64架构：22字节；arm架构：64字节；x86_64架构：8字节；其他平台：不支持。<br>**起始版本：** 20 | | ||
| 138 | - | ||
| 139 | -### ffrt_function_kind_t | ||
| 140 | - | ||
| 141 | -```c | ||
| 142 | -enum ffrt_function_kind_t | ||
| 143 | -``` | ||
| 144 | - | ||
| 145 | -**描述** | ||
| 146 | - | ||
| 147 | -任务类型。 | ||
| 148 | - | ||
| 149 | -**起始版本：** 10 | ||
| 150 | - | ||
| 151 | -| 枚举项 | 描述 | | ||
| 152 | -| -- | -- | | ||
| 153 | -| ffrt_function_kind_general | 通用任务类型 | | ||
| 154 | -| ffrt_function_kind_queue | 队列任务类型 | | ||
| 155 | - | ||
| 156 | -### ffrt_dependence_type_t | ||
| 157 | - | ||
| 158 | -```c | ||
| 159 | -enum ffrt_dependence_type_t | ||
| 160 | -``` | ||
| 161 | - | ||
| 162 | -**描述** | ||
| 163 | - | ||
| 164 | -依赖类型。 | ||
| 165 | - | ||
| 166 | -**起始版本：** 10 | ||
| 167 | - | ||
| 168 | -| 枚举项 | 描述 | | ||
| 169 | -| -- | -- | | ||
| 170 | -| ffrt_dependence_data | 数据依赖类型 | | ||
| 171 | -| ffrt_dependence_task | 任务依赖类型 | | ||
| 172 | - | ||
| 173 | -### ffrt_error_t | ||
| 174 | - | ||
| 175 | -```c | ||
| 176 | -enum ffrt_error_t | ||
| 177 | -``` | ||
| 178 | - | ||
| 179 | -**描述** | ||
| 180 | - | ||
| 181 | -FFRT错误码。 | ||
| 182 | - | ||
| 183 | -**起始版本：** 10 | ||
| 184 | - | ||
| 185 | -| 枚举项 | 描述 | | ||
| 186 | -| -- | -- | | ||
| 187 | -| ffrt_error = -1 | 失败 | | ||
| 188 | -| ffrt_success = 0 | 成功 | | ||
| 189 | -| ffrt_error_nomem = ENOMEM | 内存不足 | | ||
| 190 | -| ffrt_error_timedout = ETIMEDOUT | 超时 | | ||
| 191 | -| ffrt_error_busy = EBUSY | 重新尝试 | | ||
| 192 | -| ffrt_error_inval = EINVAL | 值无效 | | ||
| 193 | - | ||
| 194 | -### ffrt_mutex_type | ||
| 195 | - | ||
| 196 | -```c | ||
| 197 | -enum ffrt_mutex_type | ||
| 198 | -``` | ||
| 199 | - | ||
| 200 | -**描述** | ||
| 201 | - | ||
| 202 | -互斥锁类型枚举。描述互斥类型，ffrt_mutex_normal是普通互斥锁；ffrt_mutex_recursive是递归互斥锁，ffrt_mutex_default是普通互斥锁。 | ||
| 203 | - | ||
| 204 | -**起始版本：** 12 | ||
| 205 | - | ||
| 206 | -| 枚举项 | 描述 | | ||
| 207 | -| -- | -- | | ||
| 208 | -| ffrt_mutex_normal = 0 | 普通互斥锁 | | ||
| 209 | -| ffrt_mutex_recursive = 2 | 递归互斥锁 | | ||
| 210 | -| ffrt_mutex_default = ffrt_mutex_normal | 默认互斥锁 | | ||
| 211 | - | ||
| 212 | -### qos_default | ||
| 213 | - | ||
| 214 | -```c | ||
| 215 | -enum qos_default | ||
| 216 | -``` | ||
| 217 | - | ||
| 218 | -**描述** | ||
| 219 | - | ||
| 220 | 任务QoS类型枚举。 | 102 | 任务QoS类型枚举。 |
| 221 | 103 | ||
| 222 | **起始版本：** 10 | 104 | **起始版本：** 10 |
| 223 | 105 | ||
| 224 | | 枚举项 | 描述 | | 106 | | 枚举项 | 描述 | |
| 225 | | -- | -- | | 107 | | -- | -- | |
| 226 | -| qos_inherit = ffrt_qos_inherit | 继承当前任务的QoS类型 | | 108 | +| ffrt_qos_inherit = -1 | 继承。<br>继承调用线程的QoS。用于任务需要采用创建者优先级的场景。 | |
| 227 | -| qos_background = ffrt_qos_background | 后台任务 | | 109 | +| ffrt_qos_background | 后台任务。<br>最低优先级。用于用户无感知的工作，例如后台数据同步或日志刷新。 | |
| 228 | -| qos_utility = ffrt_qos_utility | 实时工具 | | 110 | +| ffrt_qos_utility | 实用工具类任务。<br>用于用户可感知但不主动等待的长时间任务，例如数据加载或内容索引。 | |
| 229 | -| qos_default = ffrt_qos_default | 默认类型 | | 111 | +| ffrt_qos_default | 默认类型。<br>无特殊QoS要求时使用的默认QoS，适用于大多数一般任务。 | |
| 230 | -| qos_user_initiated = ffrt_qos_user_initiated | 用户期望 | | 112 | +| ffrt_qos_user_initiated | 用户发起的任务。<br>用于用户主动触发、需要快速响应但不阻塞UI的任务，例如打开文档或执行搜索。 | |
| 231 | -| qos_deadline_request = ffrt_qos_deadline_request | 时限请求<br>**起始版本：** 23 | | 113 | +| ffrt_qos_deadline_request | 时限请求任务。<br>用于有明确截止时间的任务，系统优先保障其调度资源。<br>**起始版本：** 23 | |
| 232 | -| qos_user_interactive = ffrt_qos_user_interactive | 用户交互<br>**起始版本：** 23 | | 114 | +| ffrt_qos_user_interactive | 用户交互任务。<br>适用于UI响应等需要立即与用户交互的操作。<br>**起始版本：** 23 | |
| 233 | -| qos_max = ffrt_qos_user_interactive | 最高QoS等级<br>**起始版本：** 23 | | 115 | +| ffrt_qos_max = ffrt_qos_user_interactive | 最高QoS等级。<br>等价于ffrt_qos_user_interactive。<br>**起始版本：** 23 | |
| 116 | + | ||
| 117 | +### ffrt_storage_size_t | ||
| 118 | + | ||
| 119 | +```c | ||
| 120 | +enum ffrt_storage_size_t | ||
| 121 | +``` | ||
| 122 | + | ||
| 123 | +**描述** | ||
| 124 | + | ||
| 125 | +多种类型结构体的存储大小定义，单位是字节。 | ||
| 126 | + | ||
| 127 | +**起始版本：** 10 | ||
| 128 | + | ||
| 129 | +| 枚举项 | 描述 | | ||
| 130 | +| -- | -- | | ||
| 131 | +| ffrt_task_attr_storage_size = 128 | 任务属性存储大小，单位是字节。 | | ||
| 132 | +| ffrt_auto_managed_function_storage_size = 64 + sizeof(ffrt_function_header_t) | 任务执行体存储大小，单位是字节。 | | ||
| 133 | +| ffrt_mutex_storage_size = 64 | 互斥锁存储大小，单位是字节。 | | ||
| 134 | +| ffrt_cond_storage_size = 64 | 条件变量存储大小，单位是字节。 | | ||
| 135 | +| ffrt_queue_attr_storage_size = 128 | 队列属性存储大小，单位是字节。 | | ||
| 136 | +| ffrt_rwlock_storage_size = 64 | 读写锁存储大小，单位是字节。<br>**起始版本：** 18 | | ||
| 137 | +| ffrt_fiber_storage_size| 纤程存储大小，单位是字节。该常量定义纤程存储大小。实际值取决于目标架构：aarch64架构：22字节；arm架构：64字节；x86_64架构：8字节；其他平台：不支持。<br>**起始版本：** 20 | | ||
| 138 | +### ffrt_function_kind_t | ||
| 139 | + | ||
| 140 | +```c | ||
| 141 | +enum ffrt_function_kind_t | ||
| 142 | +``` | ||
| 143 | + | ||
| 144 | +**描述** | ||
| 145 | + | ||
| 146 | +任务类型枚举，用于区分通用并发任务和队列调度的任务。 | ||
| 147 | + | ||
| 148 | +**起始版本：** 10 | ||
| 149 | + | ||
| 150 | +| 枚举项 | 描述 | | ||
| 151 | +| -- | -- | | ||
| 152 | +| ffrt_function_kind_general | 通用任务。任务可提交到FFRT调度器并发执行。 | | ||
| 153 | +| ffrt_function_kind_queue | 队列任务。任务通过队列按提交顺序依次执行。 | | ||
| 154 | + | ||
| 155 | +### ffrt_dependence_type_t | ||
| 156 | + | ||
| 157 | +```c | ||
| 158 | +enum ffrt_dependence_type_t | ||
| 159 | +``` | ||
| 160 | + | ||
| 161 | +**描述** | ||
| 162 | + | ||
| 163 | +依赖类型枚举。用于指定任务间的依赖关系（数据就绪或任务完成）。 | ||
| 164 | + | ||
| 165 | +**起始版本：** 10 | ||
| 166 | + | ||
| 167 | +| 枚举项 | 描述 | | ||
| 168 | +| -- | -- | | ||
| 169 | +| ffrt_dependence_data | 数据依赖类型。任务仅在所引用的数据就绪后被调度。 | | ||
| 170 | +| ffrt_dependence_task | 任务依赖类型。任务仅在所引用的任务完成后被调度。 | | ||
| 171 | + | ||
| 172 | +### ffrt_error_t | ||
| 173 | + | ||
| 174 | +```c | ||
| 175 | +enum ffrt_error_t | ||
| 176 | +``` | ||
| 177 | + | ||
| 178 | +**描述** | ||
| 179 | + | ||
| 180 | +错误码枚举，由FFRT接口返回。 | ||
| 181 | + | ||
| 182 | +**起始版本：** 10 | ||
| 183 | + | ||
| 184 | +| 枚举项 | 描述 | | ||
| 185 | +| -- | -- | | ||
| 186 | +| ffrt_error = -1 | 通用错误。 | | ||
| 187 | +| ffrt_success = 0 | 成功。 | | ||
| 188 | +| ffrt_error_nomem = ENOMEM | 内存不足错误。 | | ||
| 189 | +| ffrt_error_timedout = ETIMEDOUT | 超时错误。 | | ||
| 190 | +| ffrt_error_busy = EBUSY | 资源忙碌错误。资源正忙，请稍后重试。 | | ||
| 191 | +| ffrt_error_inval = EINVAL | 无效值错误。 | | ||
| 192 | + | ||
| 193 | +### ffrt_mutex_type | ||
| 194 | + | ||
| 195 | +```c | ||
| 196 | +enum ffrt_mutex_type | ||
| 197 | +``` | ||
| 198 | + | ||
| 199 | +**描述** | ||
| 200 | + | ||
| 201 | +互斥锁类型枚举。 | ||
| 202 | + | ||
| 203 | +**起始版本：** 12 | ||
| 204 | + | ||
| 205 | +| 枚举项 | 描述 | | ||
| 206 | +| -- | -- | | ||
| 207 | +| ffrt_mutex_normal = 0 | 普通互斥锁类型。 | | ||
| 208 | +| ffrt_mutex_recursive = 2 | 递归互斥锁类型，允许同一线程对同一互斥锁多次加锁。 | | ||
| 209 | +| ffrt_mutex_default = ffrt_mutex_normal | 默认互斥锁类型，等价于`ffrt_mutex_normal`。 | | ||
| 210 | + | ||
| 211 | +### qos_default | ||
| 212 | + | ||
| 213 | +```c | ||
| 214 | +enum qos_default | ||
| 215 | +``` | ||
| 216 | + | ||
| 217 | +**描述** | ||
| 218 | + | ||
| 219 | +任务QoS类型枚举。各枚举值与[ffrt_qos_default_t](capi-type-def-h.md#ffrt_qos_default_t)中对应的枚举值等价。 | ||
| 220 | + | ||
| 221 | +**起始版本：** 10 | ||
| 222 | + | ||
| 223 | +| 枚举项 | 描述 | | ||
| 224 | +| -- | -- | | ||
| 225 | +| qos_inherit = ffrt_qos_inherit | 继承。<br>继承调用线程的QoS。用于任务需要采用创建者优先级的场景。 | | ||
| 226 | +| qos_background = ffrt_qos_background | 后台任务。<br>最低优先级。用于用户无感知的工作，例如后台数据同步或日志刷新。 | | ||
| 227 | +| qos_utility = ffrt_qos_utility | 实用工具类任务。<br>用于用户可感知但不主动等待的长时间任务，例如数据加载或内容索引。 | | ||
| 228 | +| qos_default = ffrt_qos_default | 默认类型。<br>无特殊QoS要求时使用的默认QoS，适用于大多数一般任务。 | | ||
| 229 | +| qos_user_initiated = ffrt_qos_user_initiated | 用户发起的任务。<br>用于用户主动触发、需要快速响应但不阻塞UI的任务，例如打开文档或执行搜索。 | | ||
| 230 | +| qos_deadline_request = ffrt_qos_deadline_request | 时限请求任务。<br>用于有明确截止时间的任务，系统优先保障其调度资源。<br>**起始版本：** 23 | | ||
| 231 | +| qos_user_interactive = ffrt_qos_user_interactive | 用户交互任务。<br>适用于UI响应等需要立即与用户交互的操作。<br>**起始版本：** 23 | | ||
| 232 | +| qos_max = ffrt_qos_user_interactive | 最高QoS等级。<br>等价于ffrt_qos_user_interactive。<br>**起始版本：** 23 | | ||
| 234 | 233 | ||
| 235 | 234 | ||
| 236 | ## 函数说明 | 235 | ## 函数说明 |
| @@ -243,7 +242,7 @@ typedef void(*ffrt_function_t)(void*) | |||
| 243 | 242 | ||
| 244 | **描述** | 243 | **描述** |
| 245 | 244 | ||
| 246 | -任务执行函数指针类型。 | 245 | +任务执行函数指针类型。函数指针定义了FFRT任务的入口点。FFRT在调度执行任务时调用该函数，并通过参数传入用户数据指针。 |
| 247 | 246 | ||
| 248 | **起始版本：** 10 | 247 | **起始版本：** 10 |
| 249 | 248 | ||
| @@ -255,10 +254,17 @@ typedef void (*ffrt_poller_cb)(void* data, uint32_t event) | |||
| 255 | 254 | ||
| 256 | **描述** | 255 | **描述** |
| 257 | 256 | ||
| 258 | -poller回调函数定义。 | 257 | +poller回调函数类型。当poller检测到已注册事件时调用该回调。`data`指针携带注册时传入的用户数据，`event`值标识触发的事件类型。 |
| 259 | 258 | ||
| 260 | **起始版本：** 12 | 259 | **起始版本：** 12 |
| 261 | 260 | ||
| 261 | +**参数：** | ||
| 262 | + | ||
| 263 | +| 参数项 | 描述 | | ||
| 264 | +| -- | -- | | ||
| 265 | +| void\* data | 指向poller注册时传入的用户数据指针。 | | ||
| 266 | +| uint32_t event | 触发回调的事件类型。 | | ||
| 267 | + | ||
| 262 | ### ffrt_timer_cb() | 268 | ### ffrt_timer_cb() |
| 263 | 269 | ||
| 264 | ```c | 270 | ```c |
| @@ -267,8 +273,14 @@ typedef void (*ffrt_timer_cb)(void* data) | |||
| 267 | 273 | ||
| 268 | **描述** | 274 | **描述** |
| 269 | 275 | ||
| 270 | -timer回调函数定义。 | 276 | +定时器回调函数类型。当定时器到期时调用该回调。`data`指针携带定时器注册时传入的用户数据。 |
| 271 | 277 | ||
| 272 | **起始版本：** 12 | 278 | **起始版本：** 12 |
| 273 | 279 | ||
| 280 | +**参数：** | ||
| 281 | + | ||
| 282 | +| 参数项 | 描述 | | ||
| 283 | +| -- | -- | | ||
| 284 | +| void\* data | 指向定时器注册时传入的用户数据指针。 | | ||
| 285 | + | ||
| 274 | 286 | ||
❌疑似检测出标点符号问题
错误原因：英文逗号后面跟了空格，在中文文档中应该使用中文逗号 建议修改为：
,const ffrt_condattr_t* attr)](#ffrt_cond_init) | 初始化条件变量。该条件变量不再使用时，必须通过[ffrt_cond_destroy](capi-condition-variable-h.md#ffrt_cond_destroy)销毁。 |操作日志