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 * @brief Enumerates the task types. 153 * 154 * @since 10 155 */ 156 typedef enum { 157 /** General task. */ 158 ffrt_function_kind_general, 159 /** Queue task. */ 160 ffrt_function_kind_queue, 161 } ffrt_function_kind_t; 162 163 /** 164 * @brief Enumerates the dependency types. 165 * 166 * @since 10 167 */ 168 typedef enum { 169 /** Data dependency type. */ 170 ffrt_dependence_data, 171 /** Task dependency type. */ 172 ffrt_dependence_task, 173 } ffrt_dependence_type_t; 174 175 /** 176 * @brief Defines the dependency data structure. 177 * 178 * @since 10 179 */ 180 typedef struct { 181 /** Dependency type. */ 182 ffrt_dependence_type_t type; 183 /** Dependency pointer. */ 184 const void* ptr; 185 } ffrt_dependence_t; 186 187 /** 188 * @brief Defines the dependency structure. 189 * 190 * @since 10 191 */ 192 typedef struct { 193 /** Number of dependencies. */ 194 uint32_t len; 195 /** Dependency data. */ 196 const ffrt_dependence_t* items; 197 } ffrt_deps_t; 198 199 /** 200 * @brief Defines the task attribute structure. 201 * 202 * @since 10 203 */ 204 typedef struct { 205 /** An array of uint32_t used to store the task attribute. */ 206 uint32_t storage[(ffrt_task_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 207 } ffrt_task_attr_t; 208 209 /** 210 * @brief Defines the queue attribute structure. 211 * 212 * @since 10 213 */ 214 typedef struct { 215 /** An array of uint32_t used to store the queue attribute. */ 216 uint32_t storage[(ffrt_queue_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 217 } ffrt_queue_attr_t; 218 219 /** 220 * @brief Defines the task handle, which identifies different tasks. 221 * 222 * @since 10 223 */ 224 typedef void* ffrt_task_handle_t; 225 226 /** 227 * @brief Enumerates the ffrt error codes. 228 * 229 * @since 10 230 */ 231 typedef enum { 232 /** A generic error. */ 233 ffrt_error = -1, 234 /** Success. */ 235 ffrt_success = 0, 236 /** An out of memory error. */ 237 ffrt_error_nomem = ENOMEM, 238 /** A timeout error. */ 239 ffrt_error_timedout = ETIMEDOUT, 240 /** A busy error. */ 241 ffrt_error_busy = EBUSY, 242 /** A invalid value error. */ 243 ffrt_error_inval = EINVAL 244 } ffrt_error_t; 245 246 /** 247 * @brief Defines the condition variable attribute structure. 248 * 249 * @since 10 250 */ 251 typedef struct { 252 /** A long integer used to store the condition variable attribute. */ 253 long storage; 254 } ffrt_condattr_t; 255 256 /** 257 * @brief Defines the mutex attribute structure. 258 * 259 * @since 10 260 */ 261 typedef struct { 262 /** A long integer used to store the mutex attribute. */ 263 long storage; 264 } ffrt_mutexattr_t; 265 266 /** 267 * @brief Defines the rwlock attribute structure. 268 * 269 * @since 18 270 */ 271 typedef struct { 272 /** A long integer used to store the rwlock attribute. */ 273 long storage; 274 } ffrt_rwlockattr_t; 275 276 /** 277 * @brief Enumerates the mutex types. 278 * 279 * Describes the mutex type, ffrt_mutex_normal is normal mutex; 280 * ffrt_mutex_recursive is recursive mutex, ffrt_mutex_default is normal mutex. 281 * 282 * @since 12 283 */ 284 typedef enum { 285 /** Normal mutex type. */ 286 ffrt_mutex_normal = 0, 287 /** Recursive mutex type. */ 288 ffrt_mutex_recursive = 2, 289 /** Default mutex type. */ 290 ffrt_mutex_default = ffrt_mutex_normal 291 } ffrt_mutex_type; 292 293 /** 294 * @brief Defines the mutex structure. 295 * 296 * @since 10 297 */ 298 typedef struct { 299 /** An array of uint32_t used to store the mutex. */ 300 uint32_t storage[(ffrt_mutex_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 301 } ffrt_mutex_t; 302 303 /** 304 * @brief Defines the rwlock structure. 305 * 306 * @since 18 307 */ 308 typedef struct { 309 /** An array of uint32_t used to store the rwlock. */ 310 uint32_t storage[(ffrt_rwlock_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 311 } ffrt_rwlock_t; 312 313 /** 314 * @brief Defines the condition variable structure. 315 * 316 * @since 10 317 */ 318 typedef struct { 319 /** An array of uint32_t used to store the condition variable. */ 320 uint32_t storage[(ffrt_cond_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; 321 } ffrt_cond_t; 322 323 /** 324 * @brief Defines the fiber structure. 325 * 326 * @since 20 327 */ 328 typedef struct { 329 /** An array of uint32_t used to store the fiber. */ 330 uintptr_t storage[ffrt_fiber_storage_size]; 331 #ifdef TSAN_MODE 332 void *tsanFiber = nullptr; 333 #endif 334 } ffrt_fiber_t; 335 336 /** 337 * @brief Defines the poller callback function type. 338 * 339 * @since 12 340 */ 341 typedef void (*ffrt_poller_cb)(void* data, uint32_t event); 342 343 /** 344 * @brief Defines the timer callback function type. 345 * 346 * @since 12 347 */ 348 typedef void (*ffrt_timer_cb)(void* data); 349 350 /** 351 * @brief Defines the timer handler. 352 * 353 * @since 12 354 */ 355 typedef int ffrt_timer_t; 356 357 #ifdef __cplusplus 358 namespace ffrt { 359 360 /** 361 * @brief Enumerates the task QoS types. 362 * 363 * @since 10 364 */ 365 enum qos_default { 366 /** Inheritance. */ 367 qos_inherit = ffrt_qos_inherit, 368 /** Background task. */ 369 qos_background = ffrt_qos_background, 370 /** Real-time tool. */ 371 qos_utility = ffrt_qos_utility, 372 /** Default type. */ 373 qos_default = ffrt_qos_default, 374 /** User initiated. */ 375 qos_user_initiated = ffrt_qos_user_initiated, 376 }; 377 378 /** 379 * @brief Defines the QoS type. 380 * 381 * @since 10 382 */ 383 using qos = int; 384 385 } 386 387 #endif // __cplusplus 388 #endif // FFRT_API_C_TYPE_DEF_H 389 /** @} */ 390