From d707d6d71d277181efda329e1e7314890347469c Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 10:44:31 +0800 Subject: [PATCH 1/7] add fiber doc Signed-off-by: huanghf --- .../ffrt/ffrt-api-guideline-c.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md b/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md index 09b9e785934..3cf1eb8c973 100644 --- a/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2495,3 +2495,61 @@ FFRT_C_API int ffrt_loop_timer_stop(ffrt_loop_t loop, ffrt_timer_t handle); return 0; } ``` + +## 纤程 + +### ffrt_fiber_t + +#### 声明 + +```c +struct ffrt_fiber_t; +``` + +#### 描述 + +`ffrt_fiber_t`为纤程存储实体类型，用于保存和恢复执行上下文。 + +#### 方法 + +##### ffrt_fiber_init + +声明 + +```c +FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* arg, void* stack, size_t stack_size); +``` + +参数 + +- `fiber`：纤程指针。 +- `func`：纤程启动时的函数指针入口。 +- `arg`：纤程启动时的函数入参。 +- `stack`：纤程运行时使用的栈空间起始地址。 +- `stack_size`：纤程栈大小，单位为字节。 + +返回值 + +- 初始化成功返回`ffrt_success`，否则返回`ffrt_error`。通常原因为`stack_size`不满足最小栈空间（不同平台存在差异）限制，建议设置4KB以上的栈空间。 + +描述 + +- 该函数用于初始化纤程，需要传入纤程启动的函数指针和入参，以及运行时使用的栈空间，纤程不管理任何的内存，纤程栈生命周期由调用方管理。 + +##### ffrt_fiber_switch + +声明 + +```c +FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to); +``` + +参数 + +- `from`：调用该函数的线程会暂停当前任务的执行，并保存当前上下文到`from`指向的纤程。 +- `to`：将`to`指向的纤程恢复到当前上下文，调用该函数的线程将执行`to`对应的任务。 + +描述 + +- 切换纤程上下文，调用该函数的线程会暂停当前任务的执行，保存当前上下文到`from`指向的纤程，并将`to`指向的纤程恢复到当前上下文，执行`to`对应的任务。 +- 注意：本接口对`from`、`to`的有效性无法做判断，调用方需自行校验地址有效性，否则会导致该进程崩溃。 -- Gitee From 22c788dab0514cd18d88282e8936c3200485d223 Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 11:01:24 +0800 Subject: [PATCH 2/7] update c en doc Signed-off-by: huanghf --- .../ffrt/ffrt-api-guideline-c.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/en/application-dev/ffrt/ffrt-api-guideline-c.md b/en/application-dev/ffrt/ffrt-api-guideline-c.md index 762183ce744..f2d0901ef57 100644 --- a/en/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/en/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2495,3 +2495,66 @@ Description return 0; } ``` + +## Fiber process + +### ffrt_fiber_t + +#### Declaration + +```c +struct ffrt_fiber_t; +``` + +#### Description + +`Ffrt_fiber_t 'is a fiber storage entity type used to store and restore execution context. + +#### Method + +##### ffrt_fiber_init + +Declaration + +```c +FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* arg, void* stack, size_t stack_size); +``` + +Parameters + +- `fiber`: Fiber pointer. +- `func`: The function pointer entry at fiber startup. +- ` arg `: Function parameter at fiber startup. +- `stack`: The starting address of the stack space used by the fiber during runtime. +- `stack_size`: The size of the fiber stack, measured in bytes. + +Return Values + +- Initialize successfully and return `ffrt_succee`, otherwise return `ffrt_error`. The usual reason is that the `stack_size` does not + meet the minimum stack space limit (which varies among different platforms), and it is recommended to set a stack space of 4KB or more. + +Description + +- This function is used to initialize the fiber, which requires passing in the function pointer and parameters for starting the fiber, + as well as the stack space used at runtime. The fiber does not manage any memory, and the lifecycle of the fiber stack is managed by + the caller. + +##### ffrt_fiber_switch + +Declaration + +```c +FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to); +``` + +Parameters + +- `from`: The thread calling this function will pause the execution of the current task and save the current context to the fiber pointed to by `from`. +- `to`: Restore the fiber pointed to by `to` to the current context, and the thread calling this function will execute the task corresponding to `to`. + +Description + +- Switching the fiber context, the thread calling this function will pause the execution of the current task, save the current context to the fiber + pointed to by `from`, and restore the fiber pointed to by `to` to the current context, executing the task corresponding to `to`. +- Note: This interface cannot determine the validity of `from` and `to`. The caller needs to verify the address validity themselves, otherwise it will + cause the process to crash. -- Gitee From e8af64af36db43556d0c0e9d070a63433c9c5022 Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 11:05:12 +0800 Subject: [PATCH 3/7] update c en doc Signed-off-by: huanghf --- en/application-dev/ffrt/ffrt-api-guideline-c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/application-dev/ffrt/ffrt-api-guideline-c.md b/en/application-dev/ffrt/ffrt-api-guideline-c.md index f2d0901ef57..404f312ccee 100644 --- a/en/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/en/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2508,7 +2508,7 @@ struct ffrt_fiber_t; #### Description -`Ffrt_fiber_t 'is a fiber storage entity type used to store and restore execution context. +`Ffrt_fiber_t` is a fiber storage entity type used to store and restore execution context. #### Method @@ -2524,7 +2524,7 @@ Parameters - `fiber`: Fiber pointer. - `func`: The function pointer entry at fiber startup. -- ` arg `: Function parameter at fiber startup. +- `arg`: Function parameter at fiber startup. - `stack`: The starting address of the stack space used by the fiber during runtime. - `stack_size`: The size of the fiber stack, measured in bytes. -- Gitee From eb77c33f4d231a13be29b7e8102c15016ca3d1cf Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 11:21:57 +0800 Subject: [PATCH 4/7] update c en doc Signed-off-by: huanghf --- en/application-dev/ffrt/ffrt-api-guideline-c.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/en/application-dev/ffrt/ffrt-api-guideline-c.md b/en/application-dev/ffrt/ffrt-api-guideline-c.md index 404f312ccee..55f3d352cbb 100644 --- a/en/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/en/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2530,14 +2530,11 @@ Parameters Return Values -- Initialize successfully and return `ffrt_succee`, otherwise return `ffrt_error`. The usual reason is that the `stack_size` does not - meet the minimum stack space limit (which varies among different platforms), and it is recommended to set a stack space of 4KB or more. +- Initialize successfully and return `ffrt_succee`, otherwise return `ffrt_error`. The usual reason is that the `stack_size` does not meet the minimum stack space limit (which varies among different platforms), and it is recommended to set a stack space of 4KB or more. Description -- This function is used to initialize the fiber, which requires passing in the function pointer and parameters for starting the fiber, - as well as the stack space used at runtime. The fiber does not manage any memory, and the lifecycle of the fiber stack is managed by - the caller. +- This function is used to initialize the fiber, which requires passing in the function pointer and parameters for starting the fiber, as well as the stack space used at runtime. The fiber does not manage any memory, and the lifecycle of the fiber stack is managed by the caller. ##### ffrt_fiber_switch @@ -2554,7 +2551,5 @@ Parameters Description -- Switching the fiber context, the thread calling this function will pause the execution of the current task, save the current context to the fiber - pointed to by `from`, and restore the fiber pointed to by `to` to the current context, executing the task corresponding to `to`. -- Note: This interface cannot determine the validity of `from` and `to`. The caller needs to verify the address validity themselves, otherwise it will - cause the process to crash. +- Switching the fiber context, the thread calling this function will pause the execution of the current task, save the current context to the fiber pointed to by `from`, and restore the fiber pointed to by `to` to the current context, executing the task corresponding to `to`. +- Note: This interface cannot determine the validity of `from` and `to`. The caller needs to verify the address validity themselves, otherwise it will cause the process to crash. -- Gitee From db47b0cb5b643d2f60eb382443fc0a04f76ce7c1 Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 14:00:54 +0800 Subject: [PATCH 5/7] update doc Signed-off-by: huanghf --- en/application-dev/ffrt/ffrt-api-guideline-c.md | 6 +++--- zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md | 11 ++++++----- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/en/application-dev/ffrt/ffrt-api-guideline-c.md b/en/application-dev/ffrt/ffrt-api-guideline-c.md index 55f3d352cbb..ed4fecf42c4 100644 --- a/en/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/en/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2508,7 +2508,7 @@ struct ffrt_fiber_t; #### Description -`Ffrt_fiber_t` is a fiber storage entity type used to store and restore execution context. +`ffrt_fiber_t` is a fiber storage entity type used to store and restore execution context. #### Method @@ -2530,11 +2530,11 @@ Parameters Return Values -- Initialize successfully and return `ffrt_succee`, otherwise return `ffrt_error`. The usual reason is that the `stack_size` does not meet the minimum stack space limit (which varies among different platforms), and it is recommended to set a stack space of 4KB or more. +- Initialize successfully and return `ffrt_success`; otherwise, return `ffrt_error`. The common reason is that the `stack_size` does not meet the minimum stack space limit, which varies across platforms. It is recommended to set a stack space of 4KB or more. Description -- This function is used to initialize the fiber, which requires passing in the function pointer and parameters for starting the fiber, as well as the stack space used at runtime. The fiber does not manage any memory, and the lifecycle of the fiber stack is managed by the caller. +- This function initializes the fiber by passing the function pointer, parameters for starting the fiber, and the runtime stack space. The caller manages the fiber stack's lifecycle. ##### ffrt_fiber_switch diff --git a/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md b/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md index 3cf1eb8c973..57cdfba2e4c 100644 --- a/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2508,7 +2508,8 @@ struct ffrt_fiber_t; #### 描述 -`ffrt_fiber_t`为纤程存储实体类型，用于保存和恢复执行上下文。 +- 纤程是一种轻量级的用户态线程，用于在用户空间内实现高效的任务调度和上下文切换。 +- `ffrt_fiber_t`为纤程存储实体类型，用于保存和恢复执行上下文。 #### 方法 @@ -2530,11 +2531,11 @@ FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* ar 返回值 -- 初始化成功返回`ffrt_success`，否则返回`ffrt_error`。通常原因为`stack_size`不满足最小栈空间（不同平台存在差异）限制，建议设置4KB以上的栈空间。 +- 初始化成功返回`ffrt_success`，否则返回`ffrt_error`。返回错误的常见原因是`stack_size`不满足最小栈空间限制（不同平台存在差异），建议设置栈空间大小为4KB或以上。 描述 -- 该函数用于初始化纤程，需要传入纤程启动的函数指针和入参，以及运行时使用的栈空间，纤程不管理任何的内存，纤程栈生命周期由调用方管理。 +- 该函数用于初始化纤程，需要传入启动纤程的函数指针和入参，以及运行时使用的栈空间，纤程不管理任何的内存，栈的生命周期由调用方管理。 ##### ffrt_fiber_switch @@ -2551,5 +2552,5 @@ FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to); 描述 -- 切换纤程上下文，调用该函数的线程会暂停当前任务的执行，保存当前上下文到`from`指向的纤程，并将`to`指向的纤程恢复到当前上下文，执行`to`对应的任务。 -- 注意：本接口对`from`、`to`的有效性无法做判断，调用方需自行校验地址有效性，否则会导致该进程崩溃。 +- 切换纤程上下文时，调用该函数的线程会暂停当前任务，保存上下文到`from`纤程，并恢复`to`纤程上下文，执行`to`对应的任务。 +- 注意：本接口不校验对`from`、`to`的有效性，调用方需自行校验地址有效性，否则会导致该进程崩溃。 -- Gitee From 204bf98478cfc6f6b34b4a97f8338d52693f2b23 Mon Sep 17 00:00:00 2001 From: huanghf Date: Thu, 3 Jul 2025 14:47:36 +0800 Subject: [PATCH 6/7] update doc Signed-off-by: huanghf --- .../ffrt/ffrt-api-guideline-c.md | 58 ------------------- 1 file changed, 58 deletions(-) diff --git a/en/application-dev/ffrt/ffrt-api-guideline-c.md b/en/application-dev/ffrt/ffrt-api-guideline-c.md index ed4fecf42c4..762183ce744 100644 --- a/en/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/en/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2495,61 +2495,3 @@ Description return 0; } ``` - -## Fiber process - -### ffrt_fiber_t - -#### Declaration - -```c -struct ffrt_fiber_t; -``` - -#### Description - -`ffrt_fiber_t` is a fiber storage entity type used to store and restore execution context. - -#### Method - -##### ffrt_fiber_init - -Declaration - -```c -FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* arg, void* stack, size_t stack_size); -``` - -Parameters - -- `fiber`: Fiber pointer. -- `func`: The function pointer entry at fiber startup. -- `arg`: Function parameter at fiber startup. -- `stack`: The starting address of the stack space used by the fiber during runtime. -- `stack_size`: The size of the fiber stack, measured in bytes. - -Return Values - -- Initialize successfully and return `ffrt_success`; otherwise, return `ffrt_error`. The common reason is that the `stack_size` does not meet the minimum stack space limit, which varies across platforms. It is recommended to set a stack space of 4KB or more. - -Description - -- This function initializes the fiber by passing the function pointer, parameters for starting the fiber, and the runtime stack space. The caller manages the fiber stack's lifecycle. - -##### ffrt_fiber_switch - -Declaration - -```c -FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to); -``` - -Parameters - -- `from`: The thread calling this function will pause the execution of the current task and save the current context to the fiber pointed to by `from`. -- `to`: Restore the fiber pointed to by `to` to the current context, and the thread calling this function will execute the task corresponding to `to`. - -Description - -- Switching the fiber context, the thread calling this function will pause the execution of the current task, save the current context to the fiber pointed to by `from`, and restore the fiber pointed to by `to` to the current context, executing the task corresponding to `to`. -- Note: This interface cannot determine the validity of `from` and `to`. The caller needs to verify the address validity themselves, otherwise it will cause the process to crash. -- Gitee From 97a14a20cd71f50fc2434f99e42ccb75db174b2c Mon Sep 17 00:00:00 2001 From: huanghf Date: Fri, 4 Jul 2025 09:11:14 +0800 Subject: [PATCH 7/7] fix Signed-off-by: huanghf --- zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md b/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md index 57cdfba2e4c..426b1882576 100644 --- a/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md +++ b/zh-cn/application-dev/ffrt/ffrt-api-guideline-c.md @@ -2531,7 +2531,8 @@ FFRT_C_API int ffrt_fiber_init(ffrt_fiber_t* fiber, void(*func)(void*), void* ar 返回值 -- 初始化成功返回`ffrt_success`，否则返回`ffrt_error`。返回错误的常见原因是`stack_size`不满足最小栈空间限制（不同平台存在差异），建议设置栈空间大小为4KB或以上。 +- 初始化成功返回`ffrt_success`，否则返回`ffrt_error`。 +- 返回错误的常见原因是`stack_size`不满足最小栈空间限制（不同平台存在差异），建议设置栈空间大小为4KB或以上。 描述 @@ -2553,4 +2554,4 @@ FFRT_C_API void ffrt_fiber_switch(ffrt_fiber_t* from, ffrt_fiber_t* to); 描述 - 切换纤程上下文时，调用该函数的线程会暂停当前任务，保存上下文到`from`纤程，并恢复`to`纤程上下文，执行`to`对应的任务。 -- 注意：本接口不校验对`from`、`to`的有效性，调用方需自行校验地址有效性，否则会导致该进程崩溃。 +- 注意：本接口不校验`from`、`to`的有效性，调用方需自行校验地址有效性，否则会导致该进程崩溃。 -- Gitee