名称	描述
FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr)	初始化任务属性。调用成功后，任务属性将被设置为默认值（如默认QoS为ffrt_qos_default）。使用完毕后须调用ffrt_task_attr_destroy释放任务属性。
FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name)	设置任务属性的名称。
FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr)	获取任务属性的名称。
FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr)	销毁任务属性。必须在已通过ffrt_task_attr_init初始化的任务属性上调用本接口，用于释放属性持有的资源。销毁后该任务属性不可再使用。
FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos)	设置任务属性的QoS。QoS用于控制任务的调度优先级。例如，对用户交互型任务配置高QoS以保证响应速度，对后台或维护型任务配置低QoS以减少其对系统资源的占用。
FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr)	获取任务属性的QoS。
FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us)	设置任务属性的延迟时间。
FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr)	获取任务属性的延迟时间。
FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority)	设置任务属性的优先级。
FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr)	获取任务属性的优先级。
FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size)	设置任务属性的栈大小。
FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr)	获取任务属性的栈大小。
FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos)	更新当前任务的QoS。在任务执行过程中需要根据运行阶段动态调整调度优先级时使用本接口。例如，一个后台同步任务在用户触发相关操作后，可通过本接口提升QoS等级以加快处理速度。
FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void)	获取当前任务的QoS。
FFRT_C_API uint64_t ffrt_this_task_get_id(void)	获取当前任务的ID。
FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind)	申请函数执行结构体的内存。申请的内存用作任务执行体封装，在通过ffrt_submit_base或ffrt_submit_h_base提交任务时传入。该内存在所提交任务执行完成后由FFRT运行时自动释放，调用方无需手动释放。
FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)	提交任务调度执行。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系和任务QoS确定任务的执行时机并选择工作线程执行该任务。本接口为底层提交接口，若任务不需要销毁回调，可使用简化接口ffrt_submit_f。与ffrt_submit_h_base的区别在于本接口不返回任务句柄，适用于不需要对已提交任务进行后续依赖管理或等待的场景。若任务属性中已通过ffrt_task_attr_set_delay设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。
FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)	提交任务调度执行并返回任务句柄。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系确定任务的执行时机。返回的任务句柄可用于通过ffrt_wait_deps等待任务完成，或作为其他任务的输入依赖以构建任务间的依赖关系。本接口为返回任务句柄的底层提交接口，若任务不需要销毁回调，可使用简化接口ffrt_submit_h_f。返回的任务句柄需通过ffrt_task_handle_destroy销毁，引用计数可通过ffrt_task_handle_inc_ref和ffrt_task_handle_dec_ref管理。
FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)	提交任务调度执行，是ffrt_submit_base接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（ffrt_function_kind_general），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过ffrt_submit_base接口提交。若任务属性中已通过ffrt_task_attr_set_delay设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。
FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)	提交任务调度执行并返回任务句柄，是ffrt_submit_h_base接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（ffrt_function_kind_general），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过ffrt_submit_h_base接口提交。若任务属性中已通过ffrt_task_attr_set_delay设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。返回的任务句柄需通过ffrt_task_handle_destroy销毁。
FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle)	增加任务句柄的引用计数。任务句柄的引用计数加一，并返回增加前的引用计数值。
FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle)	减少任务句柄的引用计数。任务句柄的引用计数减一，并返回减少前的引用计数值。本接口应与ffrt_task_handle_inc_ref配对使用，句柄不再使用时需通过ffrt_task_handle_destroy销毁。
FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle)	销毁任务句柄。调用后，任务句柄被销毁并释放关联的资源，句柄不可再使用。
FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps)	阻塞当前任务，等待依赖任务完成后再继续执行。
FFRT_C_API void ffrt_wait(void)	阻塞当前任务，等待所有已提交任务完成后再继续执行。

函数说明

[h2]ffrt_task_attr_init()

FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr)

描述

初始化任务属性。调用成功后，任务属性将被设置为默认值（如默认QoS为ffrt_qos_default）。使用完毕后须调用ffrt_task_attr_destroy释放任务属性。

起始版本： 10

参数：

参数项	描述
ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API int	任务属性初始化成功时返回0；否则返回-1。

类型

说明

FFRT_C_API int

任务属性初始化成功时返回0；

否则返回-1。

[h2]ffrt_task_attr_set_name()

FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name)

描述

设置任务属性的名称。

起始版本： 10

参数：

参数项	描述
ffrt_task_attr_t* attr	指向任务属性的指针。
const char* name	指向任务名称的指针。

[h2]ffrt_task_attr_get_name()

FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr)

描述

获取任务属性的名称。

起始版本： 10

参数：

参数项	描述
const ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API const char*	任务名称获取成功时返回非空的任务名称指针；否则返回空指针。

类型

说明

FFRT_C_API const char*

任务名称获取成功时返回非空的任务名称指针；

否则返回空指针。

[h2]ffrt_task_attr_destroy()

FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr)

描述

销毁任务属性。必须在已通过ffrt_task_attr_init初始化的任务属性上调用本接口，用于释放属性持有的资源。销毁后该任务属性不可再使用。

起始版本： 10

参数：

参数项	描述
ffrt_task_attr_t* attr	指向任务属性的指针。

[h2]ffrt_task_attr_set_qos()

FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos)

描述

设置任务属性的QoS。QoS用于控制任务的调度优先级。例如，对用户交互型任务配置高QoS以保证响应速度，对后台或维护型任务配置低QoS以减少其对系统资源的占用。

起始版本： 10

参数：

参数项	描述
ffrt_task_attr_t* attr	指向任务属性的指针。
ffrt_qos_t qos	待设置的QoS等级，取值参考ffrt_qos_t。

[h2]ffrt_task_attr_get_qos()

FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr)

描述

获取任务属性的QoS。

起始版本： 10

参数：

参数项	描述
const ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API ffrt_qos_t	QoS等级，默认返回ffrt_qos_default。

[h2]ffrt_task_attr_set_delay()

FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us)

描述

设置任务属性的延迟时间。

起始版本： 10

参数：

参数项	描述
ffrt_task_attr_t* attr	指向任务属性的指针。
uint64_t delay_us	任务延迟时间，单位是微秒。

[h2]ffrt_task_attr_get_delay()

FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr)

描述

获取任务属性的延迟时间。

起始版本： 10

参数：

参数项	描述
const ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API uint64_t	任务延迟时间，单位是微秒。

[h2]ffrt_task_attr_set_queue_priority()

FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority)

描述

设置任务属性的优先级。

起始版本： 12

参数：

参数项	描述
ffrt_task_attr_t* attr	指向任务属性的指针。
ffrt_queue_priority_t priority	并发队列任务的执行优先级，取值参考ffrt_queue_priority_t；在同一并发队列内，高优先级任务优先于低优先级任务被调度。超出合法范围的值会被静默忽略。

[h2]ffrt_task_attr_get_queue_priority()

FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr)

描述

获取任务属性的优先级。

起始版本： 12

参数：

参数项	描述
const ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API ffrt_queue_priority_t	并发队列任务的优先级。

[h2]ffrt_task_attr_set_stack_size()

FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size)

描述

设置任务属性的栈大小。

起始版本： 12

参数：

参数项

描述

ffrt_task_attr_t* attr

指向任务属性的指针。

uint64_t size

任务栈大小，单位是字节。需大于系统支持的最小栈大小，否则可能导致栈溢出；

设置过大时可能导致内存分配失败。

[h2]ffrt_task_attr_get_stack_size()

FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr)

描述

获取任务属性的栈大小。

起始版本： 12

参数：

参数项	描述
const ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API uint64_t	任务栈大小，单位是字节。

[h2]ffrt_this_task_update_qos()

FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos)

描述

更新当前任务的QoS。在任务执行过程中需要根据运行阶段动态调整调度优先级时使用本接口。例如，一个后台同步任务在用户触发相关操作后，可通过本接口提升QoS等级以加快处理速度。

起始版本： 10

参数：

参数项	描述
ffrt_qos_t qos	任务待更新的QoS等级，取值参考ffrt_qos_t。

返回：

类型	说明
FFRT_C_API int	QoS更新成功，或新QoS与当前QoS相同时返回0； QoS映射未注册、当前任务为空，或当前任务非通用类型任务（即非通过ffrt_submit_base或ffrt_submit_h_base提交的任务）时返回1。

类型

说明

FFRT_C_API int

QoS更新成功，或新QoS与当前QoS相同时返回0；

QoS映射未注册、当前任务为空，或当前任务非通用类型任务（即非通过ffrt_submit_base或ffrt_submit_h_base提交的任务）时返回1。

参考：

ffrt_this_task_get_qos

[h2]ffrt_this_task_get_qos()

FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void)

描述

获取当前任务的QoS。

起始版本： 12

返回：

类型	说明
FFRT_C_API ffrt_qos_t	任务QoS。

[h2]ffrt_this_task_get_id()

FFRT_C_API uint64_t ffrt_this_task_get_id(void)

描述

获取当前任务的ID。

起始版本： 10

返回：

类型	说明
FFRT_C_API uint64_t	当前运行任务的唯一任务ID。

[h2]ffrt_alloc_auto_managed_function_storage_base()

FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind)

描述

申请函数执行结构体的内存。申请的内存用作任务执行体封装，在通过ffrt_submit_base或ffrt_submit_h_base提交任务时传入。该内存在所提交任务执行完成后由FFRT运行时自动释放，调用方无需手动释放。

起始版本： 10

参数：

参数项	描述
ffrt_function_kind_t kind	函数执行结构体类型。通用类型适用于通过ffrt_submit_base或ffrt_submit_h_base提交的任务，队列类型适用于通过并发队列提交接口提交的任务。

参数项

描述

ffrt_function_kind_t kind

函数执行结构体类型。通用类型适用于通过ffrt_submit_base或ffrt_submit_h_base提交的任务，

队列类型适用于通过并发队列提交接口提交的任务。

返回：

类型	说明
FFRT_C_API void *	内存申请成功时返回非空指针；否则返回空指针。

类型

说明

FFRT_C_API void *

内存申请成功时返回非空指针；

否则返回空指针。

参考：

ffrt_submit_base

ffrt_submit_h_base

[h2]ffrt_submit_base()

FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)

描述

提交任务调度执行。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系和任务QoS确定任务的执行时机并选择工作线程执行该任务。本接口为底层提交接口，若任务不需要销毁回调，可使用简化接口ffrt_submit_f。与ffrt_submit_h_base的区别在于本接口不返回任务句柄，适用于不需要对已提交任务进行后续依赖管理或等待的场景。若任务属性中已通过ffrt_task_attr_set_delay设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。

起始版本： 10

参数：

参数项	描述
ffrt_function_header_t* f	任务执行体封装的指针，需通过ffrt_alloc_auto_managed_function_storage_base申请内存，且必须包含任务销毁回调函数。
const ffrt_deps_t* in_deps	指向输入依赖的指针。
const ffrt_deps_t* out_deps	指向输出依赖的指针。
const ffrt_task_attr_t* attr	指向任务属性的指针。

参考：

ffrt_submit_h_base

[h2]ffrt_submit_h_base()

FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)

描述

提交任务调度执行并返回任务句柄。任务执行体、输入依赖、输出依赖和任务属性被一同提交到FFRT调度器，调度器根据依赖关系确定任务的执行时机。返回的任务句柄可用于通过ffrt_wait_deps等待任务完成，或作为其他任务的输入依赖以构建任务间的依赖关系。本接口为返回任务句柄的底层提交接口，若任务不需要销毁回调，可使用简化接口ffrt_submit_h_f。返回的任务句柄需通过ffrt_task_handle_destroy销毁，引用计数可通过ffrt_task_handle_inc_ref和ffrt_task_handle_dec_ref管理。

起始版本： 10

参数：

参数项	描述
ffrt_function_header_t* f	任务执行体封装的指针，需通过ffrt_alloc_auto_managed_function_storage_base申请内存，且必须包含任务销毁回调函数。
const ffrt_deps_t* in_deps	指向输入依赖的指针。
const ffrt_deps_t* out_deps	指向输出依赖的指针。
const ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API ffrt_task_handle_t	任务提交成功时返回非空的任务句柄；否则返回空指针。

类型

说明

FFRT_C_API ffrt_task_handle_t

任务提交成功时返回非空的任务句柄；

否则返回空指针。

参考：

ffrt_submit_base

[h2]ffrt_submit_f()

FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)

描述

提交任务调度执行，是ffrt_submit_base接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（ffrt_function_kind_general），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过ffrt_submit_base接口提交。若任务属性中已通过ffrt_task_attr_set_delay设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。

起始版本： 20

参数：

参数项	描述
ffrt_function_t func	待执行的任务函数。
void* arg	指向传递给任务函数的参数或闭包数据的指针。
const ffrt_deps_t* in_deps	指向输入依赖的指针。
const ffrt_deps_t* out_deps	指向输出依赖的指针。
const ffrt_task_attr_t* attr	指向任务属性的指针。

参考：

ffrt_submit_base

[h2]ffrt_submit_h_f()

FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)

描述

提交任务调度执行并返回任务句柄，是ffrt_submit_h_base接口的简化形式。该接口将给定的任务函数及其参数包装为通用任务结构体（ffrt_function_kind_general），其中用于处理执行后清理的任务销毁回调（after_func）会被设为NULL，因而省略任何额外清理动作。封装后的任务结构体随后通过ffrt_submit_h_base接口提交。若任务属性中已通过ffrt_task_attr_set_delay设置延迟时间，则输入输出依赖关系不再生效，任务在延迟结束后被调度。返回的任务句柄需通过ffrt_task_handle_destroy销毁。

起始版本： 20

参数：

参数项	描述
ffrt_function_t func	待执行的任务函数。
void* arg	指向传递给任务函数的参数或闭包数据的指针。
const ffrt_deps_t* in_deps	指向输入依赖的指针。
const ffrt_deps_t* out_deps	指向输出依赖的指针。
const ffrt_task_attr_t* attr	指向任务属性的指针。

返回：

类型	说明
FFRT_C_API ffrt_task_handle_t	任务提交成功时返回非空的任务句柄；否则返回空指针。

类型

说明

FFRT_C_API ffrt_task_handle_t

任务提交成功时返回非空的任务句柄；

否则返回空指针。

参考：

ffrt_submit_h_base

[h2]ffrt_task_handle_inc_ref()

FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle)

描述

增加任务句柄的引用计数。任务句柄的引用计数加一，并返回增加前的引用计数值。

起始版本： 12

参数：

参数项	描述
ffrt_task_handle_t handle	任务句柄，由ffrt_submit_h_base或ffrt_submit_h_f返回。

返回：

类型	说明
FFRT_C_API uint32_t	任务句柄增加前的引用计数值；若handle为null则返回UINT_MAX。

[h2]ffrt_task_handle_dec_ref()

FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle)

描述

减少任务句柄的引用计数。任务句柄的引用计数减一，并返回减少前的引用计数值。本接口应与ffrt_task_handle_inc_ref配对使用，句柄不再使用时需通过ffrt_task_handle_destroy销毁。

起始版本： 12

参数：

参数项	描述
ffrt_task_handle_t handle	任务句柄。

返回：

类型	说明
FFRT_C_API uint32_t	任务句柄减少前的引用计数值；若handle为null则返回UINT_MAX。

[h2]ffrt_task_handle_destroy()

FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle)

描述

销毁任务句柄。调用后，任务句柄被销毁并释放关联的资源，句柄不可再使用。

起始版本： 10

参数：

参数项	描述
ffrt_task_handle_t handle	任务句柄。

[h2]ffrt_wait_deps()

FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps)

描述

阻塞当前任务，等待依赖任务完成后再继续执行。

起始版本： 10

参数：

参数项	描述
const ffrt_deps_t* deps	指向依赖任务列表的指针。阻塞当前任务，直到该依赖列表引用的所有任务执行完毕。

[h2]ffrt_wait()

FFRT_C_API void ffrt_wait(void)

描述

阻塞当前任务，等待所有已提交任务完成后再继续执行。

起始版本： 10

目录

task.h

概述

汇总

[h2]函数

函数说明

[h2]ffrt_task_attr_init()

[h2]ffrt_task_attr_set_name()

[h2]ffrt_task_attr_get_name()

[h2]ffrt_task_attr_destroy()

[h2]ffrt_task_attr_set_qos()

[h2]ffrt_task_attr_get_qos()

[h2]ffrt_task_attr_set_delay()

[h2]ffrt_task_attr_get_delay()

[h2]ffrt_task_attr_set_queue_priority()

[h2]ffrt_task_attr_get_queue_priority()

[h2]ffrt_task_attr_set_stack_size()

[h2]ffrt_task_attr_get_stack_size()

[h2]ffrt_this_task_update_qos()

[h2]ffrt_this_task_get_qos()

[h2]ffrt_this_task_get_id()

[h2]ffrt_alloc_auto_managed_function_storage_base()

[h2]ffrt_submit_base()

[h2]ffrt_submit_h_base()

[h2]ffrt_submit_f()

[h2]ffrt_submit_h_f()

[h2]ffrt_task_handle_inc_ref()

[h2]ffrt_task_handle_dec_ref()

[h2]ffrt_task_handle_destroy()

[h2]ffrt_wait_deps()

[h2]ffrt_wait()