proxying.h¶
Emscripten proxying.h API は、ターゲットスレッドで実行される作業をディスパッチし、オプションでその作業が完了するまでブロックするメカニズムを提供します。これは、特定の JS API が特定の スレッドでのみ呼び出すことができる Web コンテキストで特に役立ちます。どのスレッドでも、API 呼び出しを正しいスレッドにプロキシすることで、これらの API にアクセスできます。プロキシは、非同期 JS タスクを同期インターフェースでラップするのにも役立ちます。呼び出し元スレッドは、非同期タスクを専用のワーカースレッドにプロキシし、ワーカースレッドが最終的にタスクを完了したとマークするまで、おそらく JS イベントループに複数回戻った後で、待機できます。
ターゲットスレッドでは、キューに入れられた作業は 2 つの方法で実行できます。まず、ユーザーは emscripten_proxy_execute_queue を明示的に呼び出して、現在のスレッド用にキューに入れられたタスクを実行できます。または、ターゲットスレッドが JS イベントループに戻ると、たとえば emscripten_exit_with_live_runtime を介して、キューに入れられた作業が自動的に実行されます。
プロキシ API の使用方法の例については、test_pthread_proxying.c と test_pthread_proxying_cpp.cpp を参照してください。
API リファレンス¶
型¶
-
em_proxying_queue¶ 他のスレッドから非同期または同期的にプロキシできる、スレッドローカルの作業キュー（スレッドごとに 1 つ）の不透明なハンドル。
プロキシされた作業は、ライブスレッドランタイムでのみ完了できます。そのため、ユーザーは、スレッドが終了する前にプロキシされたすべての作業が完了するか、スレッドがライブランタイムで終了するように、たとえば、
emscripten_exit_with_live_runtimeを介して、ドロップされた作業を回避する必要があります。
-
em_proxying_ctx¶ 現在実行中のプロキシされたタスクの不透明なハンドル。タスクの終了を通知するために使用されます。
関数¶
-
em_proxying_queue*
em_proxying_queue_create()¶ 新しいプロキシキューを割り当てます。
- void
em_proxying_queue_destroy(em_proxying_queue* q)¶ プロキシキューを解放します。キューには、残りのキューに入れられた作業があってはなりません。
-
em_proxying_queue*
emscripten_proxy_get_system_queue()¶ 低レベルのランタイム作業のプロキシに使用されるキューを取得します。このキューでの作業は、システム関数内でいつでも処理される可能性があるため、ネイティブシグナルハンドラーと同様に、いつでも実行できるように、ブロックしないで安全である必要があります。ユーザーコードは通常、この関数を使用すべきではありません。
- void
emscripten_proxy_execute_queue(em_proxying_queue* q)¶ 指定されたキューで、現在のスレッド用にキューに入れられたすべてのタスクを実行します。この実行と同時にキューに入れられた新しいタスクも実行されます。この関数は、空のキューが検出されると返ります。
- void
emscripten_proxy_finish(em_proxying_ctx* ctx)¶ emscripten_proxy_sync_with_ctxでプロキシされたタスクの終了を通知します。
- int
emscripten_proxy_async(em_proxying_queue* q, pthread_t target_thread, void (*func)(void*), void* arg)¶ 指定されたキューとスレッドで引数
argで呼び出されるfuncをキューに入れ、funcの実行を待たずにすぐに返ります。作業が正常にキューに入れられた場合は 1 を、それ以外の場合は 0 を返します。
- int
emscripten_proxy_sync(em_proxying_queue* q, pthread_t target_thread, void (*func)(void*), void* arg)¶ 指定されたキューとスレッドで引数
argで呼び出されるfuncをキューに入れ、funcが同期的に実行されるのを待ってから返ります。funcが正常に完了した場合は 1 を返し、それ以外の場合、ターゲットスレッドがキャンセルされた場合や、作業が完了する前に終了した場合など、0 を返します。
- int
emscripten_proxy_sync_with_ctx(em_proxying_queue* q, pthread_t target_thread, void (*func)(em_proxying_ctx*, void*), void* arg)¶ emscripten_proxy_syncと同じですが、プロキシされた関数の戻りを待つ代わりに、プロキシされたタスクがemscripten_proxy_finishで明示的に完了したとマークされるのを待ちます。func自体がemscripten_proxy_finishを呼び出す必要はありません。代わりに、コンテキストポインターを格納し、任意の後でemscripten_proxy_finishを呼び出すことができます。
- int
emscripten_proxy_callback(em_proxying_queue* q, pthread_t target_thread, void (*func)(void*), void (*callback)(void*), void (*cancel)(void*), void* arg)¶ 指定されたキューとスレッドで
funcをキューに入れます。実行が完了すると（完了した場合）、同じキューで現在のスレッドにcallbackが非同期的にプロキシされます。または、作業が完了する前にターゲットスレッドが終了した場合は、代わりにcancelがプロキシバックされます。3 つの関数すべてが同じ引数argを受け取ります。funcが正常にキューイングされ、ターゲットスレッドに通知された場合は 1 を、それ以外の場合は 0 を返します。
- int
emscripten_proxy_callback_with_ctx(em_proxying_queue* q, pthread_t target_thread, void (*func)(em_proxying_ctx*, void*), void (*callback)(void*), void (*cancel)(void*), void* arg)¶ 指定されたキューとスレッドで
funcをキューに入れます。指定されたem_proxying_ctxでemscripten_proxy_finishを呼び出すことによってタスクを完了すると（完了した場合）、同じキューで現在のスレッドにcallbackが非同期的にプロキシされます。または、作業が完了する前にターゲットスレッドが終了した場合は、代わりにcancelがプロキシバックされます。3 つの関数すべてが同じ引数argを受け取ります。funcが正常にキューイングされ、ターゲットスレッドに通知された場合は 1 を、それ以外の場合は 0 を返します。
C++ API¶
この C++ API は、C++11 以降でコンパイルするときに proxying.h によって提供されます。これは、名前空間 emscripten 内で定義されています。
-
型
ProxyingQueue¶ em_proxying_queue*をラップする、薄い C++ ラッパー。-
型
ProxyingCtx¶
em_proxying_ctx*をラップする、薄い C++ ラッパー。-
void
execute()¶ ラップされた
em_proxying_queue*に対してemscripten_proxy_execute_queueを呼び出します。
-
bool
proxyAsync(pthread_t target, std::function<void()> &&func)¶ funcを実行するためにemscripten_proxy_asyncを呼び出し、関数が正常にエンキューされた場合はtrueを、それ以外の場合はfalseを返します。
-
bool
proxySync(const pthread_t target, const std::function<void()> &func)¶ funcを実行するためにemscripten_proxy_syncを呼び出し、関数が正常に完了した場合はtrueを、それ以外の場合はfalseを返します。
-
bool
proxySyncWithCtx(const pthread_t target, const std::function<void(ProxyingCtx)> &func)¶ funcを実行するためにemscripten_proxy_sync_with_ctxを呼び出し、関数がemscripten_proxy_finishまたはProxyingCtx::finishで正常に完了したとマークされた場合はtrueを、それ以外の場合はfalseを返します。
-
bool
proxyCallback(pthread_t target, std::function<void()> &&funcstd::function<void()> &&callbackstd::function<void()> &&cancel)¶ funcを実行し、callbackまたはcancelのいずれかをスケジュールするためにemscripten_proxy_callbackを呼び出し、関数が正常にエンキューされた場合はtrueを、それ以外の場合はfalseを返します。
-
bool
proxyCallbackWithCtx(pthread_t target, std::function<void(ProxyingCtx)> &&func, std::function<void()> &&callbackstd::function<void()> &&cancel)¶ funcを実行し、callbackまたはcancelのいずれかをスケジュールするためにemscripten_proxy_callback_with_ctxを呼び出し、関数が正常にエンキューされた場合はtrueを、それ以外の場合はfalseを返します。
-
型