IT评测·应用市场-qidao123.com技术社区

标题: 鸿蒙HarmonyOS APP开辟之FFRT 开辟 [打印本页]

---

作者: 王國慶    时间: 2024-11-24 08:16
标题: 鸿蒙HarmonyOS APP开辟之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）学习路线与学习文档给大家用来跟着学习。
针对一些列因素，整理了一套纯血版鸿蒙（HarmonyOS Next）全栈开辟技术的学习路线，包罗了鸿蒙开辟必把握的核心知识要点，内容有（ArkTS、ArkUI开辟组件、Stage模子、多端摆设、分布式应用开辟、WebGL、元服务、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony驱动开辟、系统定制移植等等）鸿蒙（HarmonyOS NEXT）技术知识点。

《鸿蒙 (Harmony OS)开辟学习手册》（共计892页）:https://gitcode.com/HarmonyOS_MN

怎样快速入门？

1.根本概念
2.构建第一个ArkTS应用
3.……

开辟基础知识

1.应用基础知识
2.设置文件
3.应用数据管理
4.应用安全管理
5.应用隐私保护
6.三方应用调用管控机制
7.资源分类与访问
8.学习ArkTS语言
9.……

基于ArkTS 开辟

1.Ability开辟
2.UI开辟
3.公共事件与关照
4.窗口管理
5.媒体
6.安全
7.网络与链接
8.电话服务
9.数据管理
10.后台任务(Background Task)管理
11.装备管理
12.装备使用信息统计
13.DFX
14.国际化开辟
15.折叠屏系列
16.……

鸿蒙开辟面试真题（含参考答案）:https://gitcode.com/HarmonyOS_MN

OpenHarmony 开辟环境搭建:https://gitcode.com/HarmonyOS_MN

《OpenHarmony源码解析》:https://gitcode.com/HarmonyOS_MN

搭建开辟环境
系统架构分析

• 构建子系统
  
• 启动流程
  
• 子系统
  
• 分布式任务调度子系统
  
• 分布式通讯子系统
  
• 驱动子系统
  
• ……
  

OpenHarmony 装备开辟学习手册:https://gitcode.com/HarmonyOS_MN

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

---

欢迎光临 IT评测·应用市场-qidao123.com技术社区 (https://dis.qidao123.com/)

Powered by Discuz! X3.4