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*) – 現在のコンテキストを表すファイバー。これは部分的に更新され、emscripten_fiber_swap() を介して再び切り替えると、元の呼び出しから戻ったように見えます。

  • new_fiber (emscripten_fiber_t*) – ターゲットコンテキストを表すファイバー。ファイバーにエントリポイントがある場合、新しいコンテキストで呼び出され、NULL に設定されます。それ以外の場合、emscripten_fiber_t.asyncify_data がコールスタックを巻き戻すために使用されます。ファイバーが無効または不完全な場合、動作は未定義です。