fiber.h

纖程是輕量的協同執行緒。 fiber.h 標頭檔定義了在 Emscripten 中操作纖程的低階 API。纖程是使用 非同步程式碼實作的，因此如果您打算使用它們，則必須將您的程式與 ASYNCIFY 連結。

纖程旨在作為非同步控制流程結構（例如協程）的建構區塊。它們取代了 fastcomp 後端中可用的傳統協程 API。此 API 與 POSIX ucontext 相似但不同。

API 參考

類型

emscripten_fiber_t

此結構代表纖程上下文延續。執行階段不會保留對這些物件的參照，它們僅包含執行上下文切換所需資訊。但是，切換操作會更新部分內容。

void *stack_base

C 堆疊區域的上限。堆疊向下成長，因此這是堆疊指標的初始位置。必須至少對齊 16 位元組。

void *stack_limit

C 堆疊區域的下限。必須低於 emscripten_fiber_t.stack_base。

void *stack_ptr

堆疊指標的目前位置。必須介於 emscripten_fiber_t.stack_base 和 emscripten_fiber_t.stack_limit 之間。

em_arg_callback_func entry

進入點。如果不是 NULL，則在纖程切換進入時會呼叫此函式。否則，會使用 emscripten_fiber_t.asyncify_data 來回溯呼叫堆疊。

void *user_data

不透明指標，依現狀傳遞至 emscripten_fiber_t.entry。

asyncify_data_t asyncify_data

Asyncify 資料結構。用於在切換纖程時回溯和重播呼叫堆疊。

asyncify_data_t
void *stack_ptr

Asyncify 堆疊指標的目前位置。

Asyncify 堆疊與 C 堆疊不同。它包含呼叫堆疊以及 WASM 本機變數的狀態。與 C 堆疊不同，它是向上成長的。

void *stack_limit

Asyncify 堆疊區域的上限。

int rewind_id

要回溯呼叫堆疊時需要呼叫之函式的不透明控制代碼。此值僅對執行階段有意義。

警告

回溯 ID 目前是執行緒特定的。這使得無法回復從不同執行緒啟動的纖程。

函式

void emscripten_fiber_init(emscripten_fiber_t *fiber, em_arg_callback_func entry_func, void *entry_func_arg, void *c_stack, size_t c_stack_size, void *asyncify_stack, size_t asyncify_stack_size)

初始化纖程上下文。然後可以透過呼叫 emscripten_fiber_swap() 來進入它。

參數

  • fiber (emscripten_fiber_t*) – 指向纖程結構的指標。

  • entry_func (em_arg_callback_func) – 進入點函式，在第一次進入纖程時呼叫。

  • entry_func_arg (void*) – 傳遞至 entry_func 的不透明指標。

  • c_stack (void*) – 指向要用於 C 堆疊的記憶體區域的指標。必須至少對齊 16 位元組。無論成長方向為何，這都會指向堆疊的下限。

  • c_stack_size (size_t) – C 堆疊記憶體區域的大小（以位元組為單位）。

  • asyncify_stack (void*) – 指向要用於 Asyncify 堆疊的記憶體區域的指標。無特殊對齊需求。

  • asyncify_stack_size (size_t) – Asyncify 堆疊記憶體區域的大小（以位元組為單位）。

注意

如果 entry_func 傳回，則整個程式將會結束，就像 main 已傳回一樣。為了避免這種情況，您可以使用 emscripten_fiber_swap() 跳至另一個纖程。

void emscripten_fiber_init_from_current_context(emscripten_fiber_t *fiber, void *asyncify_stack, size_t asyncify_stack_size)

根據目前活動的上下文，部分初始化纖程。這是為了從纖程切換回執行緒的原始上下文所必需的。

此函式會將 emscripten_fiber_t.stack_base 和 emscripten_fiber_t.stack_limit 設定為參照目前的堆疊界限，將 emscripten_fiber_t.entry 設定為 NULL，並使 emscripten_fiber_t.asyncify_data 參照提供的 Asyncify 堆疊記憶體。其他欄位則不會變更。

此函式初始化的纖程不完整。它們僅適合作為 emscripten_fiber_swap() 的第一個引數傳遞。這樣做會完成延續，使其可以像一般的纖程一樣使用另一個 emscripten_fiber_swap() 切換回原始上下文。

參數

  • fiber (emscripten_fiber_t*) – 指向纖程結構的指標。

  • asyncify_stack (void*) – 指向要用於 Asyncify 堆疊的記憶體區域的指標。無特殊對齊需求。

  • asyncify_stack_size (size_t) – Asyncify 堆疊記憶體區域的大小（以位元組為單位）。

void emscripten_fiber_swap(emscripten_fiber_t *old_fiber, emscripten_fiber_t *new_fiber)

執行纖程上下文切換。

參數

  • old_fiber (emscripten_fiber_t*) – 代表目前上下文的纖程 (Fiber)。它將會被部分更新，例如透過另一個呼叫 emscripten_fiber_swap() 切換回該纖程，會看起來像是從原始呼叫返回。

  • new_fiber (emscripten_fiber_t*) – 代表目標上下文的纖程。如果該纖程具有進入點，它將會在新的上下文中被呼叫，並設定為 NULL。否則，會使用 emscripten_fiber_t.asyncify_data 來回溯呼叫堆疊。如果該纖程無效或不完整，則行為未定義。