鸿蒙HarmonyOS应用开辟之FFRT 开辟引导

场景介绍

Function Flow编程模子是一种基于任务和数据驱动的并发编程模子，允许开辟者通过任务及其依赖关系形貌的方式进行应用开辟。FFRT（Function Flow运行时）是支持Function Flow编程模子的软件运行时库，用于调度实验开辟者基于Function Flow编程模子开辟的应用。通过Function Flow编程模子和FFRT，开辟者可专注于应勤奋能开辟，由FFRT在运行时根据任务依赖状态和可用实验资源自动并发调度和实验任务。
本文用于引导开辟者基于Function Flow编程模子和FFRT实现并行编程。
两种编程模子

线程编程模子FFRT任务编程模子并行度发掘方式步伐员通过创建多线程并把任务分配到每个线程中实验来发掘运行时的并行度。步伐员（编译器工具或语言特性共同）静态编程时将应用分解成任务及其数据依赖关系，运行时调度器分配任务到工作线程实验。谁负责线程创建步伐员负责创建线程，线程编程模子无法约束线程的创建，滥用可能造成体系中大量线程。由调度器负责工作线程池的创建和管理，步伐员无法直接创建线程。负载均衡步伐员静态编程时将任务映射到线程，映射不公道或任务实验时间不确定造成线程负载不均。FFRT运行时根据线程实验状态调度停当任务到空闲线程实验，减轻了线程负载不均标题。调度开销线程调度由内核态调度器完成，调度开销大。FFRT运行时在用户态以协程方式调度实验，相比内核线程调度机制更为轻量，减小调度的开销，并可通过硬化调度卸载进一步减小调度开销。依赖表达线程创建时即处于可实验状态，实验时与其他线程同步操作，增长线程切换。FFRT运行时根据任务创建时显式表达的输入依赖和输出依赖关系判断任务可实验状态，当输入依赖不满足时，任务不被调度实验。 根本概念

Function Flow 任务编程模子

Function Flow编程模子允许开辟者通过任务及其依赖关系形貌的方式进行应用开辟，其重要特性包罗Task-Based 和 Data-Driven 。
Task-Based 特性

Task-Based 指在Function Flow编程模子中开辟者以任务方式来组织应用步伐表达，运行时以任务粒度实验调度。
任务界说为一种面向开辟者的编程线索和面向运行时的实验对象，通常包罗一组指令序列及其操作的数据上下文情况。
Function Flow编程模子中的任务包罗以下重要特性：

• 任务之间可指定依赖关系，依赖关系通过Data-Driven方式表达。
  
• 任务可支持嵌套，即任务在实验过程中可天生新的任务下发给运行时，形成父子任务关系。
  
• 多任务支持互同步操作，例如期待、锁、条件变量等。
  

   留意
任务颗粒度影响应用实验性能，颗粒度过小增长调度开销，颗粒度过大降低并行度。Function Flow编程模子中任务的目标颗粒度最小为100us量级，开辟者应留意公道控制任务颗粒度。
  Data-Driven 特性

Data-Driven指任务之间的依赖关系通过数据依赖表达。
任务实验过程中对其关联的数据对象进行读写操作。在Function Flow编程模子中，数据对象表达抽象为数据签名，每个数据签名唯一对应一个数据对象。
数据依赖抽象为任务所操作的数据对象的数据签名列表，包罗输入数据依赖in_deps和输出数据依赖out_deps。数据对象的签名出现在一个任务的in_deps中时，该任务称为数据对象的消耗者任务，消耗者任务实验不改变其输入数据对象的内容；数据对象的签名出现在任务的out_deps中时，该任务称为数据对象的生产者任务，生产者任务实验改变其输出数据对象的内容，从而天生该数据对象的一个新的版本。
一个数据对象可能存在多个版本，每个版本对应一个生产者任务和零个，一个或多个消耗者任务，根据生产者任务和消耗者任务的下发次序界说数据对象的多个版本的次序以及每个版本所对应的生产者和消耗者任务。
数据依赖清除的任务进入停当状态允许被调度实验，依赖清除状态指任务全部输入数据对象版本的生产者任务实验完成，且全部输出数据对象版本的全部消耗者任务实验完成的状态。
通过上述Data-Driven的数据依赖表达，FFRT在运行时可动态构建任务之间的基于生产者/消耗者的数据依赖关系并遵循任务数据依赖状态实验调度，包罗：

• Producer-Consumer 依赖
  一个数据对象版本的生产者任务和该数据对象版本的消耗者任务之间形成的依赖关系，也称为Read-after-Write依赖。
  
• Consumer-Producer 依赖
  一个数据对象版本的消耗者任务和该数据对象的下一个版本的生产者任务之间形成的依赖关系，也称为Write-after-Read依赖。
  
• Producer-Producer 依赖
  一个数据对象版本的生产者任务和该数据对象的下一个版本的生产者任务之间形成的依赖关系，也称为Write-after-Write依赖。
  

例如，如果有这么一些任务，与数据A的关系表述为：

1. task1(OUT A);
2. task2(IN A);
3. task3(IN A);
4. task4(OUT A);
5. task5(OUT A);

复制代码

   为表述方便，本文中的数据流图均以圆圈表示 Task，方块表示数据。
  可以得出以下结论：

• task1 与task2/task3 构成Producer-Consumer 依赖，即：task2/task3 需要比及task1 写完A之后才能读A。
  
• task2/task3 与task4 构成Consumer-Producer 依赖，即：task4 需要比及task2/task3 读完A之后才能写A。
  
• task4 与task5 构成Producer-Producer 依赖，即：task5 需要比及task4 写完A之后才能写A。
  

接口说明

接口名形貌ffrt_condattr_init (ffrt_condattr_t* attr)初始化条件变量属性。ffrt_condattr_destroy(ffrt_condattr_t* attr)烧毁条件变量属性。ffrt_condattr_setclock(ffrt_condattr_t* attr, ffrt_clockid_t clock)设置条件变量的时钟属性。ffrt_condattr_getclock(const ffrt_condattr_t* attr, ffrt_clockid_t* clock)获取条件变量的时钟属性。ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr)初始化条件变量。ffrt_cond_signal(ffrt_cond_t* cond)唤醒阻塞在条件变量上的一个任务。ffrt_cond_broadcast(ffrt_cond_t* cond)唤醒阻塞在条件变量上的全部任务。ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex)条件变量期待函数，条件变量不满足时阻塞当前任务。ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point)条件变量超时期待函数，条件变量不满足时阻塞当前任务，超时期待返回。ffrt_cond_destroy(ffrt_cond_t* cond)烧毁条件变量。ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr)初始化mutex。ffrt_mutex_lock(ffrt_mutex_t* mutex)获取mutex。ffrt_mutex_unlock(ffrt_mutex_t* mutex)开释mutex。ffrt_mutex_trylock(ffrt_mutex_t* mutex)实验获取mutex。ffrt_mutex_destroy(ffrt_mutex_t* mutex)烧毁mutex。ffrt_queue_attr_init(ffrt_queue_attr_t* attr)初始化串行队列属性。ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr)烧毁串行队列属性。ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos)设置串行队列qos属性。ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr)获取串行队列qos属性。ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr)创建队列。ffrt_queue_destroy(ffrt_queue_t queue)烧毁队列。ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)提交一个任务到队列中调度实验。ffrt_queue_submit_h(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)提交一个任务到队列中调度实验，并返回任务句柄。ffrt_queue_wait(ffrt_task_handle_t handle)期待队列中一个任务实验完成。ffrt_queue_cancel(ffrt_task_handle_t handle)取消队列中一个任务。ffrt_usleep(uint64_t usec)延迟usec微秒。ffrt_yield(void)当前任务自动放权，让其他任务有机会调度实验。ffrt_task_attr_init(ffrt_task_attr_t* attr)初始化任务属性。ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name)设置任务名字。ffrt_task_attr_get_name(const ffrt_task_attr_t* attr)获取任务名字。ffrt_task_attr_destroy(ffrt_task_attr_t* attr)烧毁任务属性。ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos)设置任务qos。ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr)获取任务qos。ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us)设置任务延迟时间。ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr)获取任务延迟时间。ffrt_this_task_update_qos(ffrt_qos_t qos)更新任务qos。ffrt_this_task_get_id(void)获取任务id。ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind)申请函数实验布局的内存。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_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_task_handle_destroy(ffrt_task_handle_t handle)烧毁任务句柄。ffrt_skip(ffrt_task_handle_t handle)跳过指定任务。ffrt_wait_deps(const ffrt_deps_t* deps)期待依赖的任务完成，当前任务开始实验。 函数介绍

任务管理

ffrt_submit_base

• 该接口为ffrt动态库的导出接口，基于此可以封装出C API ffrt_submit，满足二进制兼容。
  

声明

1. const int ffrt_auto_managed_function_storage_size = 64 + sizeof(ffrt_function_header_t);
2. typedef enum {
3.     ffrt_function_kind_general,
4.     ffrt_function_kind_queue
5. } ffrt_function_kind_t;
7. void* ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind);
9. typedef void(*ffrt_function_t)(void*);
10. typedef struct {
11.     ffrt_function_t exec;
12.     ffrt_function_t destroy;
13.     uint64_t reserve[2];
14. } ffrt_function_header_t;
16. void ffrt_submit_base(ffrt_function_header_t* func, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr);

复制代码

参数

kind

• function子类型，用于优化内部数据布局，默认利用ffrt_function_kind_general类型。
  

func

• CPU Function的指针，该指针实验的数据布局，按照ffrt_function_header_t界说的形貌了该CPU Task怎样实验和烧毁的函数指针，FFRT通过这两个函数指针完成Task的实验和烧毁。
  

in_deps

• 该参数是可选的。
  
• 该参数用于形貌该任务的输入依赖，FFRT 通过数据的假造所在作为数据的Signature 来建立依赖。
  

out_deps

• 该参数是可选的。
  
• 该参数用于形貌该任务的输出依赖。
  
• 留意：该依赖值本质上是一个数值，ffrt没办法区分该值是公道的还是不公道的，会假定输入的值是公道的进行处理；但不发起接纳NULL，1, 2 等值来建立依赖关系，发起接纳现实的内存所在，因为前者利用不妥会建立起不须要的依赖，影响并发。
  

attr

• 该参数是可选的。
  
• 该参数用于形貌Task 的属性，比如qos 等
  

返回值

• 不涉及。
  

形貌

• 发起用户对ffrt_submit_base进行封装后调用，具体可参考样例。
  
• ffrt_submit_base作为底层本领，利用时需要满足以下限定：
  
  
  
  • ffrt_submit_base入参中的func指针只能通过ffrt_alloc_auto_managed_function_storage_base申请，且二者的调用需逐一对应。
    
  • ffrt_alloc_auto_managed_function_storage_base申请的内存为ffrt_auto_managed_function_storage_size字节，其生命周期归ffrt管理，在该task竣事时，由FFRT自动开释，用户无需开释。
    
  
  
• ffrt_function_header_t 中界说了两个函数指针：
  
  
  
  • exec：用于形貌该Task怎样被实验，当FFRT需要实验该Task时由FFRT调用。
    
  • destroy：用于形貌该Task怎样被烧毁，当FFRT需要烧毁该Task时由FFRT调用。
    
  
  

样例

1. template<class T>
2. struct function {
3.     template<class CT>
4.     function(ffrt_function_header_t h, CT&& c) : header(h), closure(std::forward<CT>(c)) {}
5.     ffrt_function_header_t header;
6.     T closure;
7. };
9. template<class T>
10. void exec_function_wrapper(void* t)
11. {
12.     auto f = (function<std::decay_t<T>>*)t;
13.     f->closure();
14. }
16. template<class T>
17. void destroy_function_wrapper(void* t)
18. {
19.     auto f = (function<std::decay_t<T>>*)t;
20.     f->closure = nullptr;
21. }
23. template<class T>
24. inline ffrt_function_header_t* create_function_wrapper(T&& func)
25. {
26.     using function_type = function<std::decay_t<T>>;
27.     static_assert(sizeof(function_type) <= ffrt_auto_managed_function_storage_size,
28.         "size of function must be less than ffrt_auto_managed_function_storage_size");
30.     auto p = ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
31.     auto f = new (p) function_type(
32.         {exec_function_wrapper<T>, destroy_function_wrapper<T>},
33.         std::forward<T>(func));
34.     return (ffrt_function_header_t*)f;
35. }
37. static inline void submit(std::function<void()>&& func)
38. {
39.     return ffrt_submit_base(create_function_wrapper(std::move(func)), NULL, NULL, NULL);
40. }

复制代码

ffrt_wait

---

• 同步期待，与ffrt_submit_base 共同利用。 * 期待指定的数据被生产完成，或期待当前任务的全部子任务完成，在不满足条件之前，当前的实验上下文被suspend，在满足条件后规复实验。
  

声明

1. void ffrt_wait_deps(ffrt_deps_t* deps);
2. void ffrt_wait();

复制代码

参数

deps

• 需要期待被生产完成的数据的假造所在，这些所在可能作为某些任务在submit 时的out_deps，该依赖的天生见ffrt_deps_t章节，空指针表示无依赖。
  

返回值

• 不涉及。
  

形貌

• ffrt_wait_deps(deps) 用于期待deps指代的数据被生产完成才能实验后面的代码。
  
• ffrt_wait() 用于期待当前上下文提交的全部子任务（留意：不包罗孙任务和下级子任务）都完成才能实验后面的代码。
  
• 该接口支持在FFRT task 内部调用，也支持在FFRT task 外部调用。
  
• 在FFRT task 外部调用的wait 是OS 可以或许感知的期待，相对于FFRT task 内部调用的wait 是更加昂贵的，因此我们希望尽可能让更多的wait 发生在FFRT task 内部 ，而不是FFRT task 外部。
  

样例

recursive fibonacci
串行版的fibonacci 可以实现为：

1. #include <stdio.h>
3. void fib(int x, int* y) {
4.     if (x <= 1) {
5.         *y = x;
6.     } else {
7.         int y1, y2;
8.         fib(x - 1, &y1);
9.         fib(x - 2, &y2);
10.         *y = y1 + y2;
11.     }
12. }
13. int main(int narg, char** argv)
14. {
15.     int r;
16.     fib(10, &r);
17.     printf("fibonacci 10: %d\n", r);
18.     return 0;
19. }

复制代码

若要利用 FFRT 实现并行（注，对于单纯的fibonacci，单个 Task 的计算量极小，不具有并行加快的意义，但这种调用pattern 对并行编程模子的灵活性考验黑白常高的），其中1种可行的实现为：

1. #include <stdio.h>
2. #include "ffrt.h"  //包含所有ffrt涉及的头文件
4. typedef struct {
5.     int x;
6.     int* y;
7. } fib_ffrt_s;
9. typedef struct {
10.     ffrt_function_header_t header;
11.     ffrt_function_t func;
12.     ffrt_function_t after_func;
13.     void* arg;
14. } c_function;
16. static void ffrt_exec_function_wrapper(void* t)
17. {
18.     c_function* f = (c_function*)t;
19.     if (f->func) {
20.         f->func(f->arg);
21.     }
22. }
24. static void ffrt_destroy_function_wrapper(void* t)
25. {
26.     c_function* f = (c_function*)t;
27.     if (f->after_func) {
28.         f->after_func(f->arg);
29.     }
30. }
32. #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
33. static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
34.     const ffrt_function_t after_func, void* arg)
35. {
36.     FFRT_STATIC_ASSERT(sizeof(c_function) <= ffrt_auto_managed_function_storage_size,
37.         size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
38.     c_function* f = (c_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
39.     f->header.exec = ffrt_exec_function_wrapper;
40.     f->header.destroy = ffrt_destroy_function_wrapper;
41.     f->func = func;
42.     f->after_func = after_func;
43.     f->arg = arg;
44.     return (ffrt_function_header_t*)f;
45. }
47. static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
48.     void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
49. {
50.     ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
51. }
53. #define ffrt_deps_define(name, dep1, ...) const void* __v_##name[] = {dep1, ##__VA_ARGS__}; \
54.     ffrt_deps_t name = {sizeof(__v_##name) / sizeof(void*), __v_##name}
56. void fib_ffrt(void* arg)
57. {
58.     fib_ffrt_s* p = (fib_ffrt_s*)arg;
59.     int x = p->x;
60.     int* y = p->y;
62.     if (x <= 1) {
63.         *y = x;
64.     } else {
65.         int y1, y2;
66.         fib_ffrt_s s1 = {x - 1, &y1};
67.         fib_ffrt_s s2 = {x - 2, &y2};
68.         ffrt_deps_define(dx, &x);
69.         ffrt_deps_define(dy1, &y1);
70.         ffrt_deps_define(dy2, &y2);
71.         ffrt_deps_define(dy12, &y1, &y2);
72.         ffrt_submit_c(fib_ffrt, NULL, &s1, &dx, &dy1, NULL);
73.         ffrt_submit_c(fib_ffrt, NULL, &s2, &dx, &dy2, NULL);
74.         ffrt_wait_deps(&dy12);
75.         *y = y1 + y2;
76.     }
77. }
79. int main(int narg, char** argv)
80. {
81.     int r;
82.     fib_ffrt_s s = {10, &r};
83.     ffrt_deps_define(dr, &r);
84.     ffrt_submit_c(fib_ffrt, NULL, &s, NULL, &dr, NULL);
85.     ffrt_wait_deps(&dr);
86.     printf("fibonacci 10: %d\n", r);
87.     return 0;
88. }

复制代码

解析：

• 将fibonacci (x-1)和fibonacci (x-2) 作为2个Task 提交给FFRT，在两个Task 完成之后将效果累加；
  
• 虽然单个Task 只能拆分成2个SubTask 但是子Task 可以继承拆分，因此，整个计算图的并行度黑白常高的，Task 之间在FFRT 内部形成了一颗调用树；
  

   以上实现，因为需要用户显式管理数据生命周期和函数入参打包两个因素，所以使得代码实现非常复杂。
  ffrt_deps_t

• C API中对依赖数组的抽象，逻辑上等同于C++ API中的std::vector<void*>
  

声明

1. typedef enum {
2.     ffrt_dependence_data,
3.     ffrt_dependence_task,
4. } ffrt_dependence_type_t;
6. typedef struct {
7.     ffrt_dependence_type_t type;
8.     const void* ptr;
9. } ffrt_dependence_t;
11. typedef struct {
12.     uint32_t len;
13.     const ffrt_dependence_t* items;
14. } ffrt_deps_t;

复制代码

参数

len

• 所依赖的Signature的个数，取值大于等于0。
  

item

• len个Signature的起始所在指针。
  

type

• 当前依赖为数据依赖还是任务依赖。
  

ptr

• 所依赖对应Signature内容的现实所在。
  

返回值

• 不涉及。
  

形貌

• item为len个Signature的起始指针，该指针可以指向堆空间，也可以指向栈空间，但是要求分配的空间大于等于len * sizeof(ffrt_dependence_t)。
  

样例

• 创建数据依赖大概任务依赖：
  

1. // 创建数据依赖的ffrt_deps_t
2. int x = 0;
3. const std::vector<ffrt_dependence_t> in_deps = {{ffrt_dependence_data, &x}};
4. ffrt_deps_t in{static_cast<uint32_t>(in_deps.size()), in_deps.data()};
6. // 提交某个返回handle任务
7. ffrt_task_handle_t task = ffrt_submit_h_base(
8.         ffrt_create_function_wrapper(OnePlusForTest, NULL, &a), NULL, NULL, &attr);
9. // 创建任务依赖的ffrt_deps_t
10. const std::vector<ffrt_dependence_t> wait_deps = {{ffrt_dependence_task, task}};
11. ffrt_deps_t wait{static_cast<uint32_t>(wait_deps.size()), wait_deps.data()};

复制代码

ffrt_task_attr_t

---

• 界说task 的属性的辅助类，与ffrt_submit_base 共同利用。
  

声明

1. typedef enum {
2.     ffrt_qos_inherent = -1,
3.     ffrt_qos_background,
4.     ffrt_qos_utility,
5.     ffrt_qos_default,
6.     ffrt_qos_user_initiated,
7. } ffrt_qos_default_t;
9. typedef int ffrt_qos_t;
11. typedef struct {
12.     uint32_t storage[(ffrt_task_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)];
13. } ffrt_task_attr_t;
14. typedef void* ffrt_task_handle_t;
16. int ffrt_task_attr_init(ffrt_task_attr_t* attr);
17. void ffrt_task_attr_destroy(ffrt_task_attr_t* attr);
18. void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos);
19. ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr);
20. void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name);
21. const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr);
22. void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us);
23. uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr);

复制代码

参数

attr

• 创建的tasks属性的句柄。
  

qos

• qos 设定的罗列类型。
  
• inherent 是一个qos 设定策略，代表即将ffrt_submit 的task 的qos 继承当前task 的qos。
  

delay_us

• 任务延迟实验的时间，单位为us。
  

返回值

• 不涉及。
  

形貌

• attr所通报的内容会在ffrt_submit内部完成取存，ffrt_submit返回后用户即可烧毁。
  
• 约定：
  
  
  
  • 在submit 时，如果不通过task_attr 设定qos，那么默认该提交的task的qos 为ffrt_qos_default。
    
  • 在submit 时，如果通过task_attr 设定qos 为ffrt_qos_inherent，表示将该提交的task 的qos 与当前task 的qos 相同，在FFRT task 外部提交的属性为ffrt_qos_inherent 的task，其qos 为ffrt_qos_default。
    
  • 其他情况下，该提交的task 的qos 被设定为指定的值。
    
  
  
• ffrt_task_attr_t对象的置空和烧毁由用户完成，对同一个ffrt_task_attr_t仅能调用一次ffrt_task_attr_destroy，重复对同一个ffrt_task_attr_t调用ffrt_task_attr_destroy，其行为是未界说的。
  
• 在ffrt_task_attr_destroy之后再对task_attr进行访问，其行为是未界说的。
  

样例

• 提交一个qos 级别为background 的任务：
  

1. #include <stdio.h>
2. #include "ffrt.h"
4. void my_print(void* arg)
5. {
6.     printf("hello ffrt\n");
7. }
9. typedef struct {
10.     ffrt_function_header_t header;
11.     ffrt_function_t func;
12.     ffrt_function_t after_func;
13.     void* arg;
14. } c_function;
16. static void ffrt_exec_function_wrapper(void* t)
17. {
18.     c_function* f = (c_function*)t;
19.     if (f->func) {
20.         f->func(f->arg);
21.     }
22. }
24. static void ffrt_destroy_function_wrapper(void* t)
25. {
26.     c_function* f = (c_function*)t;
27.     if (f->after_func) {
28.         f->after_func(f->arg);
29.     }
30. }
32. #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
33. static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
34.     const ffrt_function_t after_func, void* arg)
35. {
36.     FFRT_STATIC_ASSERT(sizeof(c_function) <= ffrt_auto_managed_function_storage_size,
37.         size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
38.     c_function* f = (c_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
39.     f->header.exec = ffrt_exec_function_wrapper;
40.     f->header.destroy = ffrt_destroy_function_wrapper;
41.     f->func = func;
42.     f->after_func = after_func;
43.     f->arg = arg;
44.     return (ffrt_function_header_t*)f;
45. }
47. static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
48.     void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
49. {
50.     ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
51. }
53. int main(int narg, char** argv)
54. {
55.     ffrt_task_attr_t attr;
56.     ffrt_task_attr_init(&attr);
57.     ffrt_task_attr_set_qos(&attr, ffrt_qos_background);
58.     ffrt_task_attr_set_delay(&attr, 10000);
59.     ffrt_submit_c(my_print, NULL, NULL, NULL, NULL, &attr);
60.     ffrt_task_attr_destroy(&attr);
61.     ffrt_wait();
62.     return 0;
63. }

复制代码

ffrt_submit_h_base

---

• 向调度器提交一个task，与ffrt_submit_base 的差别在于返回task 的句柄，该句柄可以用于建立task 之间的依赖，或用于在wait 语句中实现同步。
  

声明

1. typedef void* ffrt_task_handle_t;
3. ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr);
4. void ffrt_task_handle_destroy(ffrt_task_handle_t handle);

复制代码

参数

func

• CPU Function的指针，该指针实验的数据布局，按照ffrt_function_header_t界说的形貌了该CPU Task怎样实验和烧毁的函数指针，FFRT通过这两个函数指针完成Task的实验和烧毁。
  

in_deps

• 该参数是可选的。
  
• 该参数用于形貌该任务的输入依赖，FFRT 通过数据的假造所在作为数据的Signature 来建立依赖。
  

out_deps

• 该参数是可选的。
  
• 该参数用于形貌该任务的输出依赖。
  
• 留意：该依赖值本质上是一个数值，ffrt没办法区分该值是公道的还是不公道的，会假定输入的值是公道的进行处理；但不发起接纳NULL，1, 2 等值来建立依赖关系，发起接纳现实的内存所在，因为前者利用不妥会建立起不须要的依赖，影响并发。
  

attr

• 该参数是可选的。
  
• 该参数用于形貌Task 的属性，比如qos 等
  

返回值

• task 的句柄，该句柄可以用于建立task 之间的依赖，或用于在wait 语句中实现同步。
  

形貌

• C API中的ffrt_task_handle_t需要用户调用ffrt_task_handle_destroy显式烧毁。
  
• C API中的task_handle_t对象的置空和烧毁由用户完成，对同一个ffrt_task_handle_t仅能调用一次ffrt_task_handle_destroy，重复对同一个ffrt_task_handle_t调用ffrt_task_handle_destroy，其行为是未界说的。
  
• 在ffrt_task_handle_destroy之后再对ffrt_task_handle_t进行访问，其行为是未界说的。
  

样例

1. #include <stdio.h>
2. #include "ffrt.h"
4. void func0(void* arg)
5. {
6.     printf("hello ");
7. }
9. void func1(void* arg)
10. {
11.     (*(int*)arg)++;
12. }
14. void func2(void* arg)
15. {
16.     printf("world, x = %d\n", *(int*)arg);
17. }
19. void func3(void* arg)
20. {
21.     printf("handle wait");
22.     (*(int*)arg)++;
23. }
25. typedef struct {
26.     ffrt_function_header_t header;
27.     ffrt_function_t func;
28.     ffrt_function_t after_func;
29.     void* arg;
30. } c_function;
32. static void ffrt_exec_function_wrapper(void* t)
33. {
34.     c_function* f = (c_function*)t;
35.     if (f->func) {
36.         f->func(f->arg);
37.     }
38. }
40. static void ffrt_destroy_function_wrapper(void* t)
41. {
42.     c_function* f = (c_function*)t;
43.     if (f->after_func) {
44.         f->after_func(f->arg);
45.     }
46. }
48. #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
49. static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
50.     const ffrt_function_t after_func, void* arg)
51. {
52.     FFRT_STATIC_ASSERT(sizeof(c_function) <= ffrt_auto_managed_function_storage_size,
53.         size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
54.     c_function* f = (c_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
55.     f->header.exec = ffrt_exec_function_wrapper;
56.     f->header.destroy = ffrt_destroy_function_wrapper;
57.     f->func = func;
58.     f->after_func = after_func;
59.     f->arg = arg;
60.     return (ffrt_function_header_t*)f;
61. }
63. static inline ffrt_task_handle_t ffrt_submit_h_c(ffrt_function_t func, const ffrt_function_t after_func,
64.     void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
65. {
66.     return ffrt_submit_h_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
67. }
69. static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
70.     void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
71. {
72.     ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
73. }
76. int main(int narg, char** argv)
77. {  
78.     // handle work with submit
79.     ffrt_task_handle_t h = ffrt_submit_h_c(func0, NULL, NULL, NULL, NULL, NULL); // not need some data in this task
80.     int x = 1;
81.     const std::vector<ffrt_dependence_t> in_deps = {{ffrt_dependence_data, &x}};
82.     ffrt_deps_t d2{static_cast<uint32_t>(in_deps.size()), in_deps.data()};
84.     const std::vector<ffrt_dependence_t> out_deps = {{ffrt_dependence_data, &x}};
85.     ffrt_deps_t d1{static_cast<uint32_t>(out_deps.size()), out_deps.data()};
87.     ffrt_submit_c(func1, NULL, &x, NULL, &d1, NULL);
88.     ffrt_submit_c(func2, NULL, &x, &d2, NULL, NULL); // this task depend x and h
89.     ffrt_task_handle_destroy(h);
90.    
91.     // handle work with wait
92.     ffrt_task_handle_t h2 = ffrt_submit_h_c(func3, NULL, &x, NULL, NULL, NULL);
94.     const std::vector<ffrt_dependence_t> wait_deps = {{ffrt_dependence_task, h2}};
95.     ffrt_deps_t d3{static_cast<uint32_t>(wait_deps.size()), wait_deps.data()};
96.     ffrt_wait_deps(&d3);
97.     ffrt_task_handle_destroy(h2);
98.     printf("x = %d", x);
99.     ffrt_wait();
100.     return 0;
101. }

复制代码

• 预期的输出为：
  

1. hello world, x = 2
2. handle wait
3. x = 3

复制代码

ffrt_this_task_get_id

---

• 返回当前task的id标识，更多利用用于维测（原因是task name可能重名）。
  

声明

1. uint64_t ffrt_this_task_get_id();

复制代码

参数

• 不涉及。
  

返回值

• 当前task的id。
  

形貌

• 该接口在task内部调用将返回当前task的id标识，在task外部调用将返回0。
  
• 可以基于该接口在task外部调用返回0的特性来区分函数是运行在FFRT 工作线程上还黑白FFRT工作线程上。
  
• task id为从1开始编码，每提交一个task便增长1，被计划成64bit，即便是每秒百万次提交，也需要292471.2年才会发生翻转。
  

样例

• 忽略。
  

ffrt_this_task_update_qos

---

• 更新当前正在实验的task的优先级。
  

声明

1. int ffrt_this_task_update_qos(ffrt_qos_t qos);

复制代码

参数

• qos 新的优先级。
  

返回值

• 0表示成功，非0表示失败。
  

形貌

• 该接口对当前task的qos调解会立即见效。
  
• 如果新设定的qos与当前的qos不一致，则会block当前task的实验，再按照新的qos规复实验。
  
• 如果新设定的qos与当前的qos一致，则接口会立即返回0，不做任那边理。
  
• 如果在非task内部调用该接口，则返回非0值，用户可以选择忽略或其他处理。
  

样例

• 忽略。
  

串行队列

---

• FFRT提供queue来实现Andorid中类似WorkQueue本领，且在利用得当的情况下将有更好的性能。
  

ffrt_queue_attr_t

声明

1. typedef struct {
2.     uint32_t storage[(ffrt_queue_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)];
3. } ffrt_queue_attr_t;
5. int ffrt_queue_attr_init(ffrt_queue_attr_t* attr);
6. void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr);

复制代码

参数

attr

• 该参数是指向未初始化的ffrt_queue_attr_t。
  

返回值

• 若成功返回0，否则返回-1。
  

形貌

• ffrt_queue_attr_t用于创建ffrt_queue_t且不单独利用，因此必须在创建队列前先创建好队列属性。
  
• ffrt_queue_attr_t对象的置空和烧毁由用户完成，对同一个ffrt_queue_attr_t仅能调用一次ffrt_queue_attr_destroy，重复对同一个ffrt_queue_attr_t调用ffrt_queue_attr_destroy，其行为是未界说的。
  
• 在ffrt_queue_attr_destroy之后再对ffrt_queue_attr_t进行访问，其行为是未界说的。
  

样例

参考ffrt_queue_t章节的样例。
ffrt_queue_t

声明

1. typedef enum { ffrt_queue_serial, ffrt_queue_max } ffrt_queue_type_t;
2. typedef void* ffrt_queue_t;
4. ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr)
5. void ffrt_queue_destroy(ffrt_queue_t queue)

复制代码

参数

type

• 该参数用于形貌创建的队列类型。
  

name

• 该参数用于形貌创建队列的名字。
  

attr

• 该参数用于形貌queue的属性，详见ffrt_queue_attr_t章节。
  

返回值

• 若成功则返回新创建的队列，否则返回空指针。
  

形貌

• 提交至该队列的任务将按照次序实验，如果某个提交的任务中发生阻塞，则无法包管该任务的实验次序。
  
• ffrt_queue_t对象的置空和烧毁由用户完成，对同一个ffrt_queue_t仅能调用一次ffrt_queue_destroy，重复对同一个ffrt_queue_t调用ffrt_queue_destroy，其行为是未界说的。
  
• 在ffrt_queue_destroy之后再对ffrt_queue_t进行访问，其行为是未界说的。
  

样例

1. #include <stdio.h>
2. #include "ffrt.h"
4. using namespace std;
6. template<class T>
7. struct Function {
8.     template<class CT>
9.     Function(ffrt_function_header_t h, CT&& c) : header(h), closure(std::forward<CT>(c)) {}
10.     ffrt_function_header_t header;
11.     T closure;
12. };
14. template<class T>
15. void ExecFunctionWrapper(void* t)
16. {
17.     auto f = reinterpret_cast<Function<std::decay_t<T>>*>(t);
18.     f->closure();
19. }
21. template<class T>
22. void DestroyFunctionWrapper(void* t)
23. {
24.     auto f = reinterpret_cast<Function<std::decay_t<T>>*>(t);
25.     f->closure = nullptr;
26. }
28. template<class T>
29. static inline ffrt_function_header_t* create_function_wrapper(T&& func,
30.     ffrt_function_kind_t kind = ffrt_function_kind_general)
31. {
32.     using function_type = Function<std::decay_t<T>>;
33.     auto p = ffrt_alloc_auto_managed_function_storage_base(kind);
34.     auto f =
35.         new (p)function_type({ ExecFunctionWrapper<T>, DestroyFunctionWrapper<T>, { 0 } }, std::forward<T>(func));
36.     return reinterpret_cast<ffrt_function_header_t*>(f);
37. }
39. int main(int narg, char** argv)
40. {
41.     ffrt_queue_attr_t queue_attr;
42.     (void)ffrt_queue_attr_init(&queue_attr);
43.     ffrt_queue_t queue_handle = ffrt_queue_create(ffrt_queue_serial, "test_queue", &queue_attr);
45.     ffrt_queue_submit(queue_handle, create_function_wrapper([]() {printf("Task done.\n");}, ffrt_function_kind_queue), nullptr);
47.     ffrt_queue_attr_destroy(&queue_attr);
48.     ffrt_queue_destroy(queue_handle);
49. }

复制代码

同步原语

ffrt_mutex_t

---

• FFRT提供的类似pthread mutex 的性能实现。
  

声明

1. typedef enum {
2.     ffrt_error = -1,
3.     ffrt_success = 0,
4.     ffrt_error_nomem = ENOMEM,
5.     ffrt_error_timedout = ETIMEDOUT,
6.     ffrt_error_busy = EBUSY,
7.     ffrt_error_inval = EINVAL
8. } ffrt_error_t;
10. struct ffrt_mutex_t;
12. int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr);
13. int ffrt_mutex_lock(ffrt_mutex_t* mutex);
14. int ffrt_mutex_unlock(ffrt_mutex_t* mutex);
15. int ffrt_mutex_trylock(ffrt_mutex_t* mutex);
16. int ffrt_mutex_destroy(ffrt_mutex_t* mutex);

复制代码

参数

attr

• 当前FFRT只支持底子类型的mutex，因此attr必须为空指针。
  

mutex

• 指向所操作的互斥锁的指针。
  

返回值

• 若成功则为 ffrt_success ，否则发生错误。
  

形貌

• 该接口只能在FFRT task 内部调用，在FFRT task 外部调用存在未界说的行为。
  
• 该功能可以或许避免pthread传统的pthread_mutex_t 在抢不到锁时陷入内核的标题，在利用得当的条件下将会有更好的性能。
  
• 留意：目前暂不支持递归和定时功能。
  
• 留意：C API中的ffrt_mutex_t需要用户调用ffrt_mutex_init和ffrt_mutex_destroy显式创建和烧毁。
  
• 留意：C API中的ffrt_mutex_t对象的置空和烧毁由用户完成，对同一个ffrt_mutex_t仅能调用一次ffrt_mutex_destroy，重复对同一个ffrt_mutex_t调用ffrt_mutex_destroy，其行为是未界说的。
  
• 留意：在ffrt_mutex_destroy之后再对ffrt_mutex_t进行访问，其行为是未界说的。
  

样例

1. #include <stdio.h>
2. #include "ffrt.h"
4. typedef struct {
5.     int* sum;
6.     ffrt_mutex_t* mtx;
7. } tuple;
9. void func(void* arg)
10. {
11.     tuple* t = (tuple*)arg;
12.    
13.     int ret = ffrt_mutex_lock(t->mtx);
14.     if (ret != ffrt_success) {
15.         printf("error\n");
16.     }
17.     (*t->sum)++;
18.     ret = ffrt_mutex_unlock(t->mtx);
19.     if (ret != ffrt_success) {
20.         printf("error\n");
21.     }
22. }
24. typedef struct {
25.     ffrt_function_header_t header;
26.     ffrt_function_t func;
27.     ffrt_function_t after_func;
28.     void* arg;
29. } c_function;
31. static void ffrt_exec_function_wrapper(void* t)
32. {
33.     c_function* f = (c_function*)t;
34.     if (f->func) {
35.         f->func(f->arg);
36.     }
37. }
39. static void ffrt_destroy_function_wrapper(void* t)
40. {
41.     c_function* f = (c_function*)t;
42.     if (f->after_func) {
43.         f->after_func(f->arg);
44.     }
45. }
47. #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
48. static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
49.     const ffrt_function_t after_func, void* arg)
50. {
51.     FFRT_STATIC_ASSERT(sizeof(c_function) <= ffrt_auto_managed_function_storage_size,
52.         size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
53.     c_function* f = (c_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
54.     f->header.exec = ffrt_exec_function_wrapper;
55.     f->header.destroy = ffrt_destroy_function_wrapper;
56.     f->func = func;
57.     f->after_func = after_func;
58.     f->arg = arg;
59.     return (ffrt_function_header_t*)f;
60. }
62. static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
63.     void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
64. {
65.     ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
66. }
68. void ffrt_mutex_task()
69. {
70.     int sum = 0;
71.     ffrt_mutex_t mtx;
72.     tuple t = {&sum, &mtx};
73.     int ret = ffrt_mutex_init(&mtx, NULL);
74.     if (ret != ffrt_success) {
75.         printf("error\n");
76.     }
77.     for (int i = 0; i < 10; i++) {
78.         ffrt_submit_c(func, NULL, &t, NULL, NULL, NULL);
79.     }
80.     ffrt_mutex_destroy(&mtx);
81.     ffrt_wait();
82.     printf("sum = %d", sum);
83. }
85. int main(int narg, char** argv)
86. {
87.     int r;
88.     ffrt_submit_c(ffrt_mutex_task, NULL, NULL, NULL, NULL, NULL);
89.     ffrt_wait();
90.     return 0;
91. }

复制代码

预期输出为：

1. sum=10

复制代码

• 该例子为功能示例，现实中并不鼓励这样利用。
  

ffrt_cond_t

---

• FFRT提供的类似pthread 信号量的性能实现。
  

声明

1. typedef enum {
2.     ffrt_error = -1,
3.     ffrt_success = 0,
4.     ffrt_error_nomem = ENOMEM,
5.     ffrt_error_timedout = ETIMEDOUT,
6.     ffrt_error_busy = EBUSY,
7.     ffrt_error_inval = EINVAL
8. } ffrt_error_t;
10. struct ffrt_cond_t;
12. int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr);
13. int ffrt_cond_signal(ffrt_cond_t* cond);
14. int ffrt_cond_broadcast(ffrt_cond_t* cond);
15. int ffrt_cond_wait(ffrt_cond_t*cond, ffrt_mutex_t* mutex);
16. int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point);
17. int ffrt_cond_destroy(ffrt_cond_t* cond);

复制代码

参数

cond

• 指向所操作的信号量的指针。
  

attr

• 属性设定，空指针表示利用默认属性。
  

mutex

• 指向要在阻塞期间解锁的互斥锁的指针。
  

time_point

• 指向指定期待时限时间的对象的指针。
  

返回值

• 若成功则为 ffrt_success，若在锁定互斥前抵达时限则为 ffrt_error_timedout。
  

形貌

• 该接口只能在FFRT task 内部调用，在FFRT task 外部调用存在未界说的行为。
  
• 该功能可以或许避免传统的pthread_cond_t在条件不满足时陷入内核的标题，在利用得当的条件下将会有更好的性能。
  
• 留意：C API中的ffrt_cond_t需要用户调用ffrt_cond_init和ffrt_cond_destroy显式创建和烧毁。
  
• 留意：C API中的ffrt_cond_t对象的置空和烧毁由用户完成，对同一个ffrt_cond_t仅能调用一次ffrt_cond_destroy，重复对同一个ffrt_cond_t调用ffrt_cond_destroy，其行为是未界说的。
  
• 留意：在ffrt_cond_destroy之后再对ffrt_cond_t进行访问，其行为是未界说的。
  

样例

1. #include <stdio.h>
2. #include "ffrt.h"
4. typedef struct {
5.     ffrt_cond_t* cond;
6.     int* a;
7.     ffrt_mutex_t* lock_;
8. } tuple;
10. void func1(void* arg)
11. {
12.     tuple* t = (tuple*)arg;
13.     int ret = ffrt_mutex_lock(t->lock_);
14.     if (ret != ffrt_success) {
15.         printf("error\n");
16.     }
17.     while (*t->a != 1) {
18.         ret = ffrt_cond_wait(t->cond, t->lock_);
19.         if (ret != ffrt_success) {
20.             printf("error\n");
21.         }
22.     }
23.     ret = ffrt_mutex_unlock(t->lock_);
24.     if (ret != ffrt_success) {
25.         printf("error\n");
26.     }
27.     printf("a = %d", *(t->a));
28. }
30. void func2(void* arg)
31. {
32.     tuple* t = (tuple*)arg;
33.     int ret = ffrt_mutex_lock(t->lock_);
34.     if (ret != ffrt_success) {
35.         printf("error\n");
36.     }
37.     *(t->a) = 1;
38.     ret = ffrt_cond_signal(t->cond);
39.     if (ret != ffrt_success) {
40.         printf("error\n");
41.     }
42.     ret = ffrt_mutex_unlock(t->lock_);
43.     if (ret != ffrt_success) {
44.         printf("error\n");
45.     }
46. }
48. typedef struct {
49.     ffrt_function_header_t header;
50.     ffrt_function_t func;
51.     ffrt_function_t after_func;
52.     void* arg;
53. } c_function;
55. static void ffrt_exec_function_wrapper(void* t)
56. {
57.     c_function* f = (c_function*)t;
58.     if (f->func) {
59.         f->func(f->arg);
60.     }
61. }
63. static void ffrt_destroy_function_wrapper(void* t)
64. {
65.     c_function* f = (c_function*)t;
66.     if (f->after_func) {
67.         f->after_func(f->arg);
68.     }
69. }
71. #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
72. static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
73.     const ffrt_function_t after_func, void* arg)
74. {
75.     FFRT_STATIC_ASSERT(sizeof(c_function) <= ffrt_auto_managed_function_storage_size,
76.         size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
77.     c_function* f = (c_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
78.     f->header.exec = ffrt_exec_function_wrapper;
79.     f->header.destroy = ffrt_destroy_function_wrapper;
80.     f->func = func;
81.     f->after_func = after_func;
82.     f->arg = arg;
83.     return (ffrt_function_header_t*)f;
84. }
86. static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
87.     void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
88. {
89.     ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
90. }
92. void ffrt_cv_task()
93. {
94.     ffrt_cond_t cond;
95.     int ret = ffrt_cond_init(&cond, NULL);
96.     if (ret != ffrt_success) {
97.         printf("error\n");
98.     }
99.     int a = 0;
100.     ffrt_mutex_t lock_;
101.     tuple t = {&cond, &a, &lock_};
102.     ret = ffrt_mutex_init(&lock_, NULL);
103.     if (ret != ffrt_success) {
104.         printf("error\n");
105.     }
106.     ffrt_submit_c(func1, NULL, &t, NULL, NULL, NULL);
107.     ffrt_submit_c(func2, NULL, &t, NULL, NULL, NULL);
108.     ffrt_wait();
109.     ffrt_cond_destroy(&cond);
110.     ffrt_mutex_destroy(&lock_);
111. }
113. int main(int narg, char** argv)
114. {
115.     ffrt_submit_c(ffrt_cv_task, NULL, NULL, NULL, NULL, NULL);
116.     ffrt_wait();
117.     return 0;
118. }

复制代码

预期输出为：

1. a=1

复制代码

• 该例子为功能示例，现实中并不鼓励这样利用。
  

杂项

ffrt_usleep

---

• FFRT提供的类似C11 sleep和linux usleep的性能实现。
  

声明

1. int ffrt_usleep(uint64_t usec);

复制代码

参数

usec

• 就寝的us数。
  

返回值

• 不涉及。
  

形貌

• 该接口只能在FFRT task 内部调用，在FFRT task 外部调用存在未界说的行为。
  
• 该功能可以或许避免传统的sleep 就寝时陷入内核的标题，在利用得当的条件下将会有更好的性能。
  

样例

1. #include <time.h>
2. #include <stdio.h>
3. #include "ffrt.h"
5. void func(void* arg)
6. {
7.     printf("Time: %s", ctime(&(time_t){time(NULL)}));
8.     ffrt_usleep(2000000); // 睡眠 2 秒
9.     printf("Time: %s", ctime(&(time_t){time(NULL)}));
10. }
12. typedef struct {
13.     ffrt_function_header_t header;
14.     ffrt_function_t func;
15.     ffrt_function_t after_func;
16.     void* arg;
17. } c_function;
19. static void ffrt_exec_function_wrapper(void* t)
20. {
21.     c_function* f = (c_function*)t;
22.     if (f->func) {
23.         f->func(f->arg);
24.     }
25. }
27. static void ffrt_destroy_function_wrapper(void* t)
28. {
29.     c_function* f = (c_function*)t;
30.     if (f->after_func) {
31.         f->after_func(f->arg);
32.     }
33. }
35. #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
36. static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
37.     const ffrt_function_t after_func, void* arg)
38. {
39.     FFRT_STATIC_ASSERT(sizeof(c_function) <= ffrt_auto_managed_function_storage_size,
40.         size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
41.     c_function* f = (c_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
42.     f->header.exec = ffrt_exec_function_wrapper;
43.     f->header.destroy = ffrt_destroy_function_wrapper;
44.     f->func = func;
45.     f->after_func = after_func;
46.     f->arg = arg;
47.     return (ffrt_function_header_t*)f;
48. }
50. static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
51.     void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
52. {
53.     ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
54. }
56. int main(int narg, char** argv)
57. {
58.     ffrt_submit_c(func, NULL, NULL, NULL, NULL, NULL);
59.     ffrt_wait();
60.     return 0;
61. }

复制代码

ffrt_yield

---

• 当前task 自动让出CPU 实验资源，让其他可以被实验的task 先实验，如果没有其他可被实验的task，yield 无效。
  

声明

1. void ffrt_yield();

复制代码

参数

• 不涉及。
  

返回值

• 不涉及。
  

形貌

• 该接口只能在FFRT task 内部调用，在FFRT task 外部调用存在未界说的行为。
  
• 此函数的确切行为取决于实现，特殊是利用中的FFRT 调度步伐的机制和体系状态。
  

样例

• 省略。
  

开辟步调

以下步调形貌了怎样利用FFRT提供的Native API接口，创建并行任务和串行队列任务以及烧毁相应资源。
添加动态链接库
CMakeLists.txt中添加以下lib：

1. libffrt.z.so

复制代码

头文件

1. #include "ffrt/task.h"
2. #include "ffrt/type_def.h"
3. #include "ffrt/condition_variable.h"
4. #include "ffrt/mutex.h"
5. #include "ffrt/queue.h"
6. #include "ffrt/sleep.h"

复制代码

• 首先需要对实验的函数进行封装。
  

1. // 第一种使用模板，支持C++
2. template<class T>
3. struct Function {
4.     template<class CT>
5.     Function(ffrt_function_header_t h, CT&& c) : header(h), closure(std::forward<CT>(c)) {}
6.     ffrt_function_header_t header;
7.     T closure;
8. };
10. template<class T>
11. void ExecFunctionWrapper(void* t)
12. {
13.     auto f = reinterpret_cast<Function<std::decay_t<T>>*>(t);
14.     f->closure();
15. }
17. template<class T>
18. void DestroyFunctionWrapper(void* t)
19. {
20.     auto f = reinterpret_cast<Function<std::decay_t<T>>*>(t);
21.     f->closure = nullptr;
22. }
24. template<class T>
25. static inline ffrt_function_header_t* create_function_wrapper(T&& func,
26.     ffrt_function_kind_t kind = ffrt_function_kind_general)
27. {
28.     using function_type = Function<std::decay_t<T>>;
29.     auto p = ffrt_alloc_auto_managed_function_storage_base(kind);
30.     auto f =
31.         new (p)function_type({ ExecFunctionWrapper<T>, DestroyFunctionWrapper<T>, { 0 } }, std::forward<T>(func));
32.     return reinterpret_cast<ffrt_function_header_t*>(f);
33. }
35. // 第二种创建方式
36. typedef struct {
37.     ffrt_function_header_t header;
38.     ffrt_function_t func;
39.     ffrt_function_t after_func;
40.     void* arg;
41. } CFunction;
43. static void FfrtExecFunctionWrapper(void* t)
44. {
45.     CFunction* f = static_cast<CFunction*>(t);
46.     if (f->func) {
47.         f->func(f->arg);
48.     }
49. }
51. static void FfrtDestroyFunctionWrapper(void* t)
52. {
53.     CFunction* f = static_cast<CFunction*>(t);
54.     if (f->after_func) {
55.         f->after_func(f->arg);
56.     }
57. }
59. #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
60. static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
61.     const ffrt_function_t after_func, void* arg, ffrt_function_kind_t kind_t = ffrt_function_kind_general)
62. {
63.     FFRT_STATIC_ASSERT(sizeof(CFunction) <= ffrt_auto_managed_function_storage_size,
64.         size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
65.     CFunction* f = static_cast<CFunction*>(ffrt_alloc_auto_managed_function_storage_base(kind_t));
66.     f->header.exec = FfrtExecFunctionWrapper;
67.     f->header.destroy = FfrtDestroyFunctionWrapper;
68.     f->func = func;
69.     f->after_func = after_func;
70.     f->arg = arg;
71.     return reinterpret_cast<ffrt_function_header_t*>(f);
72. }
74. // 样例：待提交执行的函数
75. void OnePlusForTest(void* arg)
76. {
77.     (*static_cast<int*>(arg)) += 1;
78. }

复制代码

• 设置task属性值。
  

用户提交任务时可以设置任务属性，包罗qos优先级，名称等，具体可参考接口文档。

1. // ******初始化并行任务属性******
2. ffrt_task_attr_t attr;
3. ffrt_task_attr_init(&attr);
5. // ******创建串行队列******
7. // 创建串行队列的属性
8. ffrt_queue_attr_t queue_attr;
9. // 创建串行队列的handle
10. ffrt_queue_t queue_handle;
12. // 初始化队列属性
13. (void)ffrt_queue_attr_init(&queue_attr);
15. // 如有需要，设置指定优先级
16. ffrt_queue_attr_set_qos(&queue_attr, static_cast<ffrt_qos_t>(ffrt_qos_inherit));
17. // 如有需要，设置超时时间(ms)
18. ffrt_queue_attr_set_timeout(&queue_attr, 10000);
19. // 如有需要，设置超时回调
20. int x = 0;
21. ffrt_queue_attr_set_callback(&queue_attr, ffrt_create_function_wrapper(OnePlusForTest, NULL, &x,
22.     ffrt_function_kind_queue));
24. // 基于属性，初始化队列
25. queue_handle = ffrt_queue_create(ffrt_queue_serial, "test_queue", &queue_attr);

复制代码

• 提交任务。
  

1. int a = 0;
2. // ******并行任务******
3. // 提交不带handle返回值的并行任务
4. ffrt_submit_base(ffrt_create_function_wrapper(OnePlusForTest, NULL, &a), NULL, NULL, &attr);
5. // 提交带handle返回值的并行任务
6. ffrt_task_handle_t task = ffrt_submit_h_base(
7.     ffrt_create_function_wrapper(OnePlusForTest, NULL, &a), NULL, NULL, &attr);
9. // ******串行任务******
10. // 提交不返回handle的串行队列任务
11. ffrt_queue_submit(queue_handle, ffrt_create_function_wrapper(OnePlusForTest, nullptr, &a,
12.     ffrt_function_kind_queue), nullptr);
13. // 提交带handle的串行队列任务
14. ffrt_task_handle_t handle = ffrt_queue_submit_h(queue_handle,
15.     ffrt_create_function_wrapper(OnePlusForTest, nullptr, &a, ffrt_function_kind_queue), nullptr);
17. // 如果需要等待执行结果，则调用wait
18. const std::vector<ffrt_dependence_t> wait_deps = {{ffrt_dependence_task, task}};
19. ffrt_deps_t wait{static_cast<uint32_t>(wait_deps.size()), wait_deps.data()};
20. ffrt_wait_deps(&wait);
22. ffrt_queue_wait(handle);

复制代码

• 任务提交完成后烧毁相应资源。
  

1. // ******销毁并行任务******
2. ffrt_task_attr_destroy(&attr);
3. ffrt_task_handle_destroy(task);
5. // ******销毁串行队列任务******
6. // 先销毁任务handle，再销毁队列
7. ffrt_queue_attr_destroy(&queue_attr);
8. ffrt_task_handle_destroy(handle);
9. ffrt_queue_destroy(queue_handle);

复制代码

利用发起

发起1: 函数化

根本头脑：计算过程函数化

• 步伐过程各步调以函数封装表达，函数满足类纯函数特性。
  
• 无全局数据访问。
  
• 无内部状态保留。
  
• 通过ffrt_submit_base()接口以异步任务方式提交函数实验。
  
• 将函数访问的数据对象以及访问方式在ffrt_submit_base()接口中的in_deps/out_deps参数表达。
  
• 步伐员通过inDeps/outDeps参数表达任务间依赖关系以包管步伐实验的正确性。
  

   做到纯函数的好处在于：1. 可以或许最大化发掘并行度，2.避免DataRace和锁的标题。
  在现实中，可以根据场景放松纯函数的约束，但前提是：

• 确定添加的in_deps/out_deps可确保步伐正确实验。
  
• 通过FFRT提供的锁机制保护对全局变量的访问。
  

发起2: 利用FFRT提供的替换API

• 克制在FFRT任务中利用体系线程库API创建线程，利用submit提交任务。
  
• 利用FFRT提供的锁，条件变量，就寝，IO等API代替体系线程库API。
  
  
  
  • 利用体系线程库API可能造成工作线程阻塞，引起额外性能开销。
    
  
  

发起3: Deadline机制

• 必须用于具备周期/重复实验特性的处理流程。
  
• 在有明白时间约束和性能关键的处理流程中利用，避免滥用。
  
• 在相对大颗粒度的处理流程中利用，例如具有16.6ms时间约束的帧处理流程。
  

发起4: 从线程模子迁移

• 创建线程替换为创建FFRT任务。
  
  
  
  • 线程从逻辑上类似无in_deps的任务。
    
  
  
• 识别线程间的依赖关系，并将其表达在任务的依赖关系in_deps/out_deps上。
  
• 线程内计算过程分解为异步任务调用。
  
• 通过任务依赖关系和锁机制避免并发任务数据竞争标题。
  

已知限定

C API中初始化ffrt对象后，对象的置空与烧毁由用户负责

• 为包管较高的性能，ffrt的C API中内部不包罗对对象的烧毁状态的标志，用户需要公道地进行资源的开释，重复调用各个对象的destroy操作，其效果是未界说的。
  
• 错误示例1，重复调用destroy可能造成不可预知的数据破坏。
  

1. #include "ffrt.h"
2. void abnormal_case_1()
3. {
4.     ffrt_task_handle_t h = ffrt_submit_h_base([](){printf("Test task running...\n");}, NULL, NULL, NULL, NULL, NULL);
5.     ...
6.     ffrt_task_handle_destroy(h);
7.     ffrt_task_handle_destroy(h); // double free
8. }

复制代码

• 错误示例2，未调用destroy会造成内存泄漏
  

1. #include "ffrt.h"
2. void abnormal_case_2()
3. {
4.     ffrt_task_handle_t h = ffrt_submit_h_base([](){printf("Test task running...\n");}, NULL, NULL, NULL, NULL, NULL);
5.     ...
6.     // memory leak
7. }

复制代码

• 发起示例，仅调用一次destroy，如有须要可进行置空
  

1. #include "ffrt.h"
2. void normal_case()
3. {
4.     ffrt_task_handle_t h = ffrt_submit_h_base([](){printf("Test task running...\n");}, NULL, NULL, NULL, NULL, NULL);
5.     ...
6.     ffrt_task_handle_destroy(h);
7.     h = nullptr; // if necessary
8. }

复制代码

为了能让大家更好的学习鸿蒙（HarmonyOS NEXT）开辟技能，这边特意整理了《鸿蒙开辟学习手册》（共计890页），希望对大家有所资助：https://qr21.cn/FV7h05
《鸿蒙开辟学习手册》：

怎样快速入门：https://qr21.cn/FV7h05

• 根本概念
  
• 构建第一个ArkTS应用
  
• ……
  

开辟底子知识：https://qr21.cn/FV7h05

• 应用底子知识
  
• 配置文件
  
• 应用数据管理
  
• 应用安全管理
  
• 应用隐私保护
  
• 三方应用调用管控机制
  
• 资源分类与访问
  
• 学习ArkTS语言
  
• ……
  

基于ArkTS 开辟：https://qr21.cn/FV7h05

• Ability开辟
  
• UI开辟
  
• 公共变乱与通知
  
• 窗口管理
  
• 媒体
  
• 安全
  
• 网络与链接
  
• 电话服务
  
• 数据管理
  
• 后台任务(Background Task)管理
  
• 装备管理
  
• 装备利用信息统计
  
• DFX
  
• 国际化开辟
  
• 折叠屏系列
  
• ……
  

鸿蒙开辟面试真题（含参考答案）：https://qr18.cn/F781PH

鸿蒙开辟面试大盘集篇（共计319页）：https://qr18.cn/F781PH

1.项目开辟必备面试题
2.性能优化方向
3.架构方向
4.鸿蒙开辟体系底层方向
5.鸿蒙音视频开辟方向
6.鸿蒙车载开辟方向
7.鸿蒙南向开辟方向

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。