1 /* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup FFRT 18 * @{ 19 * 20 * @brief Provides FFRT C APIs. 21 * 22 * @since 10 23 */ 24 25 /** 26 * @file type_def.h 27 * 28 * @brief Declares common types. 29 * 30 * @library libffrt.z.so 31 * @kit FunctionFlowRuntimeKit 32 * @syscap SystemCapability.Resourceschedule.Ffrt.Core 33 * @since 10 34 */ 35 36 #ifndef FFRT_API_C_TYPE_DEF_H 37 #define FFRT_API_C_TYPE_DEF_H 38 39 #include <stdint.h> 40 #include <errno.h> 41 42 #ifdef __cplusplus 43 #define FFRT_C_API extern "C" 44 #else 45 #define FFRT_C_API 46 #endif 47 48 /** 49 * @brief Enumerates the task priority types. 50 * 51 * @since 12 52 */ 53 typedef enum { 54 /** Should be distributed at once if possible, handle time equals to send time, prior to high level. */ 55 ffrt_queue_priority_immediate = 0, 56 /** High priority, sorted by handle time, prior to low level. */ 57 ffrt_queue_priority_high, 58 /** Low priority, sorted by handle time, prior to idle level. */ 59 ffrt_queue_priority_low, 60 /** Lowest priority, sorted by handle time, only distribute when there is no other level inside queue. */ 61 ffrt_queue_priority_idle, 62 } ffrt_queue_priority_t; 63 64 /** 65 * @brief Enumerates the task QoS types. 66 * 67 * @since 10 68 */ 69 typedef enum { 70 /** Inheritance. */ 71 ffrt_qos_inherit = -1, 72 /** Background task. */ 73 ffrt_qos_background, 74 /** Real-time tool. */ 75 ffrt_qos_utility, 76 /** Default type. */ 77 ffrt_qos_default, 78 /** User initiated. */ 79 ffrt_qos_user_initiated, 80 } ffrt_qos_default_t; 81 82 /** 83 * @brief Defines the QoS type. 84 * 85 * @since 10 86 */ 87 typedef int ffrt_qos_t; 88 89 /** 90 * @brief Defines the task function pointer type. 91 * 92 * @since 10 93 */ 94 typedef void(*ffrt_function_t)(void*); 95 96 /** 97 * @brief Defines a task executor. 98 * 99 * @since 10 100 */ 101 typedef struct { 102 /** Function used to execute a task. */ 103 ffrt_function_t exec; 104 /** Function used to destroy a task. */ 105 ffrt_function_t destroy; 106 /** Need to be set to 0. */ 107 uint64_t reserve[2]; 108 } ffrt_function_header_t; 109 110 /** 111 * @brief Defines the storage size of multiple types of structs. 112 * 113 * @since 10 114 */ 115 typedef enum { 116 /** Task attribute storage size. */ 117 ffrt_task_attr_storage_size = 128, 118 /** Task executor storage size. */ 119 ffrt_auto_managed_function_storage_size = 64 + sizeof(ffrt_function_header_t), 120 /** Mutex storage size. */ 121 ffrt_mutex_storage_size = 64, 122 /** Condition variable storage size. */ 123 ffrt_cond_storage_size = 64, 124 /** Queue storage size. */ 125 ffrt_queue_attr_storage_size = 128, 126 /** Rwlock storage size. 127 * 128 * @since 18 129 */ 130 ffrt_rwlock_storage_size = 64, 131 /** Fiber storage size. 132 * 133 * This constant defines the fiber storage size. 134 * The actual value depends on the target architecture: 135 * - __aarch64__: 22 136 * - __arm__: 64 137 * - __x86_64__: 8 138 * 139 * @since 20 140 */ 141 #if defined(__aarch64__) 142 ffrt_fiber_storage_size = 22, 143 #elif defined(__arm__) 144 ffrt_fiber_storage_size = 64, 145 #elif defined(__x86_64__) 146 ffrt_fiber_storage_size = 8, 147 #else 148 #error "unsupported architecture" 149 #endif 150 } ffrt_storage_size_t; 151 152 /** 153 * @brief Enumerates the task types. 154 * 155 * @since 10 156 */ 157 typedef enum { 158 /** General task. */ 159 ffrt_function_kind_general, 160 /** Queue task. */ 161 ffrt_function_kind_queue, 162 } ffrt_function_kind_t; 163 164 /** 165 * @brief Enumerates the dependency types. 166 * 167 * @since 10 168 */ 169 typedef enum { 170 /** Data dependency type. */ 171 ffrt_dependence_data, 172 /** Task dependency type. */ 173 ffrt_dependence_task, 174 } ffrt_dependence_type_t; 175 176 /** 177 * @brief Defines the dependency data structure. 178 * 179 * @since 10 180 */ 181 typedef struct { 182 /** Dependency type. */ 183 ffrt_dependence_type_t type; 184 /** Dependency pointer. */ 185 const void* ptr; 186 } ffrt_dependence_t; 187 188 /** 189 * @brief Defines the dependency structure. 190 * 191 * @since 10 192 */ 193 typedef struct { 194 /** Number of dependencies. */ 195 uint32_t len; 196 /** Dependency data. */ 197 const ffrt_dependence_t* items; 198 } ffrt_deps_t; 199 200 /** 201 * @brief Defines the task attribute structure. 202 * 203 * @since 10 204 */ 205 typedef struct { 206 /** An array of uint32_t used to store the task attribute. */ 207 uint32_t storage[(ffrt_task_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 208 } ffrt_task_attr_t; 209 210 /** 211 * @brief Defines the queue attribute structure. 212 * 213 * @since 10 214 */ 215 typedef struct { 216 /** An array of uint32_t used to store the queue attribute. */ 217 uint32_t storage[(ffrt_queue_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 218 } ffrt_queue_attr_t; 219 220 /** 221 * @brief Defines the task handle, which identifies different tasks. 222 * 223 * @since 10 224 */ 225 typedef void* ffrt_task_handle_t; 226 227 /** 228 * @brief Enumerates the ffrt error codes. 229 * 230 * @since 10 231 */ 232 typedef enum { 233 /** A generic error. */ 234 ffrt_error = -1, 235 /** Success. */ 236 ffrt_success = 0, 237 /** An out of memory error. */ 238 ffrt_error_nomem = ENOMEM, 239 /** A timeout error. */ 240 ffrt_error_timedout = ETIMEDOUT, 241 /** A busy error. */ 242 ffrt_error_busy = EBUSY, 243 /** A invalid value error. */ 244 ffrt_error_inval = EINVAL 245 } ffrt_error_t; 246 247 /** 248 * @brief Defines the condition variable attribute structure. 249 * 250 * @since 10 251 */ 252 typedef struct { 253 /** A long integer used to store the condition variable attribute. */ 254 long storage; 255 } ffrt_condattr_t; 256 257 /** 258 * @brief Defines the mutex attribute structure. 259 * 260 * @since 10 261 */ 262 typedef struct { 263 /** A long integer used to store the mutex attribute. */ 264 long storage; 265 } ffrt_mutexattr_t; 266 267 /** 268 * @brief Defines the rwlock attribute structure. 269 * 270 * @since 18 271 */ 272 typedef struct { 273 /** A long integer used to store the rwlock attribute. */ 274 long storage; 275 } ffrt_rwlockattr_t; 276 277 /** 278 * @brief Enumerates the mutex types. 279 * 280 * Describes the mutex type, ffrt_mutex_normal is normal mutex; 281 * ffrt_mutex_recursive is recursive mutex, ffrt_mutex_default is normal mutex. 282 * 283 * @since 12 284 */ 285 typedef enum { 286 /** Normal mutex type. */ 287 ffrt_mutex_normal = 0, 288 /** Recursive mutex type. */ 289 ffrt_mutex_recursive = 2, 290 /** Default mutex type. */ 291 ffrt_mutex_default = ffrt_mutex_normal 292 } ffrt_mutex_type; 293 294 /** 295 * @brief Defines the mutex structure. 296 * 297 * @since 10 298 */ 299 typedef struct { 300 /** An array of uint32_t used to store the mutex. */ 301 uint32_t storage[(ffrt_mutex_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 302 } ffrt_mutex_t; 303 304 /** 305 * @brief Defines the rwlock structure. 306 * 307 * @since 18 308 */ 309 typedef struct { 310 /** An array of uint32_t used to store the rwlock. */ 311 uint32_t storage[(ffrt_rwlock_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 312 } ffrt_rwlock_t; 313 314 /** 315 * @brief Defines the condition variable structure. 316 * 317 * @since 10 318 */ 319 typedef struct { 320 /** An array of uint32_t used to store the condition variable. */ 321 uint32_t storage[(ffrt_cond_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 322 } ffrt_cond_t; 323 324 /** 325 * @brief Defines the fiber structure. 326 * 327 * @since 20 328 */ 329 typedef struct { 330 /** An array of uint32_t used to store the fiber. */ 331 uintptr_t storage[ffrt_fiber_storage_size]; 332 } ffrt_fiber_t; 333 334 /** 335 * @brief Defines the poller callback function type. 336 * 337 * @since 12 338 */ 339 typedef void (*ffrt_poller_cb)(void* data, uint32_t event); 340 341 /** 342 * @brief Defines the timer callback function type. 343 * 344 * @since 12 345 */ 346 typedef void (*ffrt_timer_cb)(void* data); 347 348 /** 349 * @brief Defines the timer handler. 350 * 351 * @since 12 352 */ 353 typedef int ffrt_timer_t; 354 355 #ifdef __cplusplus 356 namespace ffrt { 357 358 /** 359 * @brief Enumerates the task QoS types. 360 * 361 * @since 10 362 */ 363 enum qos_default { 364 /** Inheritance. */ 365 qos_inherit = ffrt_qos_inherit, 366 /** Background task. */ 367 qos_background = ffrt_qos_background, 368 /** Real-time tool. */ 369 qos_utility = ffrt_qos_utility, 370 /** Default type. */ 371 qos_default = ffrt_qos_default, 372 /** User initiated. */ 373 qos_user_initiated = ffrt_qos_user_initiated, 374 }; 375 376 /** 377 * @brief Defines the QoS type. 378 * 379 * @since 10 380 */ 381 using qos = int; 382 383 } 384 385 #endif // __cplusplus 386 #endif // FFRT_API_C_TYPE_DEF_H 387 /** @} */