From 02f8a271f6fb07de4281fdc0c773f5d6abb8f41c Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 16:10:09 +0800 Subject: [PATCH 1/7] add fiber zh-cn doc Signed-off-by: huanghf --- .../resourceschedule/ffrt/c/fiber.h | 69 +++++++++++++++++++ .../resourceschedule/ffrt/c/type_def.h | 28 ++++++++ 2 files changed, 97 insertions(+) create mode 100644 zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h new file mode 100644 index 00000000..0e9c8ff5 --- /dev/null +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup FFRT + * @{ + * + * @brief Provides FFRT C APIs. + * + * @since 20 + */ + +/** + * @file fiber.h + * + * @brief 声明纤程c接口 + * + * @library libffrt.z.so + * @kit FunctionFlowRuntimeKit + * @syscap SystemCapability.Resourceschedule.Ffrt.Core + * @since 20 + */ + +#ifndef FFRT_API_C_FIBER_H +#define FFRT_API_C_FIBER_H + +#include "type_def.h" + +/** + * @brief 初始化一个纤程。 + * + * 此函数初始化纤程，为其执行做准备。 + * + * @param fiber 指向要初始化的纤程的指针。 + * @param func 纤程切换后所要执行的方法。 + * @param arg 纤程切换后所要执行方法的入参。 + * @param stack 纤程堆栈内存指针。 + * @param stack_size 纤程堆栈大小。 + * @return 初始化成功返回ffrt_success，否则返回ffrt_error。 + * @since 20 + */ +FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* arg, void* stack, size_t stack_size); + + +/** + * @brief 纤程切换。 + * + * 将当前上下文保存到指定的纤程中，然后通过@c from和@c to实现上下的保持和恢复，从而实现上下文切换。 + * + * @param from 将要保存的上下文的纤程指针。 + * @param to 将要恢复的上下文的纤程指针。 + * @since 20 + */ +FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to); + +#endif // FFRT_API_C_FIBER_H +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h index be68f266..b941ed19 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h @@ -129,6 +129,24 @@ typedef enum { * @since 18 */ ffrt_rwlock_storage_size = 64, + /** + * + * 纤程在不同平台下所占大小（字节） + * - __aarch64__: 22 + * - __arm__: 64 + * - __x86_64__: 8 + * + * @since 20 + */ +#if defined(__aarch64__) + ffrt_fiber_storage_size = 22, +#elif defined(__arm__) + ffrt_fiber_storage_size = 64, +#elif defined(__x86_64__) + ffrt_fiber_storage_size = 8, +#else +#error "unsupported architecture" +#endif } ffrt_storage_size_t; /** @@ -303,6 +321,16 @@ typedef struct { uint32_t storage[(ffrt_cond_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)]; } ffrt_cond_t; +/** + * @brief 纤程结构 + * + * @since 20 + */ +typedef struct { + /** 纤程上下文所占空间 */ + uintptr_t storage[ffrt_fiber_storage_size]; +} ffrt_fiber_t; + /** * @brief poller回调函数定义。 * -- Gitee From f69d705beabd00daa107a34e5f755916a08a7238 Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 19:04:50 +0800 Subject: [PATCH 2/7] format Signed-off-by: huanghf --- zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h | 14 +++++++------- .../native_sdk/resourceschedule/ffrt/c/type_def.h | 12 ++++++------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h index 0e9c8ff5..4a6f6a2d 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h @@ -25,7 +25,7 @@ /** * @file fiber.h * - * @brief 声明纤程c接口 + * @brief 声明纤程C接口 * * @library libffrt.z.so * @kit FunctionFlowRuntimeKit @@ -41,13 +41,13 @@ /** * @brief 初始化一个纤程。 * - * 此函数初始化纤程，为其执行做准备。 + * 此函数初始化纤程实例，该实例可以存储上下文。 * - * @param fiber 指向要初始化的纤程的指针。 + * @param fiber 指向要初始化的纤程的指针, 具体可参考{@link ffrt_fiber_t}。 * @param func 纤程切换后所要执行的方法。 * @param arg 纤程切换后所要执行方法的入参。 * @param stack 纤程堆栈内存指针。 - * @param stack_size 纤程堆栈大小。 + * @param stack_size 纤程堆栈大小, 具体可参考{@link ffrt_storage_size_t}。 * @return 初始化成功返回ffrt_success，否则返回ffrt_error。 * @since 20 */ @@ -57,10 +57,10 @@ FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* ar /** * @brief 纤程切换。 * - * 将当前上下文保存到指定的纤程中，然后通过@c from和@c to实现上下的保持和恢复，从而实现上下文切换。 + * 将当前上下文保存到指定纤程，并通过传参实现上下的保存和恢复，完成上下文切换。 * - * @param from 将要保存的上下文的纤程指针。 - * @param to 将要恢复的上下文的纤程指针。 + * @param from 将要保存的纤程指针。 + * @param to 将要恢复的纤程指针。 * @since 20 */ FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to); diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h index b941ed19..a19cd306 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h @@ -131,10 +131,10 @@ typedef enum { ffrt_rwlock_storage_size = 64, /** * - * 纤程在不同平台下所占大小（字节） - * - __aarch64__: 22 - * - __arm__: 64 - * - __x86_64__: 8 + * 纤程在不同平台下所占大小，单位：Byte。 + * - AArch64: 22 + * - ARM: 64 + * - X86-64: 8 * * @since 20 */ @@ -322,12 +322,12 @@ typedef struct { } ffrt_cond_t; /** - * @brief 纤程结构 + * @brief 纤程结构。 * * @since 20 */ typedef struct { - /** 纤程上下文所占空间 */ + /** 纤程上下文所占空间。 */ uintptr_t storage[ffrt_fiber_storage_size]; } ffrt_fiber_t; -- Gitee From ab7b9431efeae6cdb04efa84663ee4135fdb1c76 Mon Sep 17 00:00:00 2001 From: huanghf Date: Fri, 4 Jul 2025 09:07:32 +0800 Subject: [PATCH 3/7] update doc Signed-off-by: huanghf --- zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h index 4a6f6a2d..76b0b709 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h @@ -17,7 +17,7 @@ * @addtogroup FFRT * @{ * - * @brief Provides FFRT C APIs. + * @brief FFRT（Function Flow运行时）是支持Function Flow编程模型的软件运行时库，用于调度执行开发者基于Function Flow编程模型开发的应用。 * * @since 20 */ -- Gitee From 9b92403e3efe1a504296ab580bc9a075b08cd1e6 Mon Sep 17 00:00:00 2001 From: huanghf Date: Fri, 4 Jul 2025 09:18:29 +0800 Subject: [PATCH 4/7] fix Signed-off-by: huanghf --- zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h index 76b0b709..cf8ca36a 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h @@ -39,7 +39,7 @@ #include "type_def.h" /** - * @brief 初始化一个纤程。 + * @brief 初始化一个纤程，纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换。 * * 此函数初始化纤程实例，该实例可以存储上下文。 * @@ -57,7 +57,7 @@ FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* ar /** * @brief 纤程切换。 * - * 将当前上下文保存到指定纤程，并通过传参实现上下的保存和恢复，完成上下文切换。 + * 调用该函数的线程会暂停当前任务的执行，并将当前上下文保存到from纤程中，同时恢复to纤程中的上下文。 * * @param from 将要保存的纤程指针。 * @param to 将要恢复的纤程指针。 -- Gitee From 29f31379a8bcc359c8c9daca75e30cb70cedf003 Mon Sep 17 00:00:00 2001 From: huanghf Date: Fri, 4 Jul 2025 09:42:57 +0800 Subject: [PATCH 5/7] fix Signed-off-by: huanghf --- zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h index cf8ca36a..b98a970e 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h @@ -25,7 +25,7 @@ /** * @file fiber.h * - * @brief 声明纤程C接口 + * @brief 纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换，此为声明纤程的C接口。 * * @library libffrt.z.so * @kit FunctionFlowRuntimeKit @@ -39,7 +39,7 @@ #include "type_def.h" /** - * @brief 初始化一个纤程，纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换。 + * @brief 初始化一个纤程。 * * 此函数初始化纤程实例，该实例可以存储上下文。 * @@ -55,9 +55,7 @@ FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* ar /** - * @brief 纤程切换。 - * - * 调用该函数的线程会暂停当前任务的执行，并将当前上下文保存到from纤程中，同时恢复to纤程中的上下文。 + * @brief 纤程切换函数，调用该函数的线程会暂停当前任务的执行，并将当前上下文保存到from纤程中，同时恢复to纤程中的上下文。 * * @param from 将要保存的纤程指针。 * @param to 将要恢复的纤程指针。 -- Gitee From 8f574ed4f22403770d722be7524616c139075f87 Mon Sep 17 00:00:00 2001 From: huanghf Date: Fri, 4 Jul 2025 09:46:22 +0800 Subject: [PATCH 6/7] fix Signed-off-by: huanghf --- zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h index b98a970e..4dacdd10 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/fiber.h @@ -39,9 +39,7 @@ #include "type_def.h" /** - * @brief 初始化一个纤程。 - * - * 此函数初始化纤程实例，该实例可以存储上下文。 + * @brief 纤程初始化函数，此函数初始化纤程实例，该实例可以存储上下文。 * * @param fiber 指向要初始化的纤程的指针, 具体可参考{@link ffrt_fiber_t}。 * @param func 纤程切换后所要执行的方法。 -- Gitee From b0495c2e40811659b30e05e12ce787d10ccf8c7b Mon Sep 17 00:00:00 2001 From: huanghf Date: Fri, 4 Jul 2025 10:00:09 +0800 Subject: [PATCH 7/7] fix Signed-off-by: huanghf --- zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h b/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h index a19cd306..26cb0f69 100644 --- a/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h +++ b/zh-cn/native_sdk/resourceschedule/ffrt/c/type_def.h @@ -130,7 +130,7 @@ typedef enum { */ ffrt_rwlock_storage_size = 64, /** - * + * * 纤程在不同平台下所占大小，单位：Byte。 * - AArch64: 22 * - ARM: 64 -- Gitee