proxying.h

Emscripten proxying.h API 提供一種機制，用於將工作分派給目標執行緒執行，並可選擇性地封鎖直到該工作完成。這在 Web 環境中特別有用，因為某些 JS API 只能在特定的執行緒上呼叫；任何執行緒都可以透過將 API 呼叫代理到正確的執行緒來存取這些 API。代理對於使用同步介面包裝非同步 JS 工作也很有用。呼叫執行緒可以將非同步工作代理給專用的工作執行緒，並等待工作執行緒最終將工作標記為完成，可能在多次返回 JS 事件迴圈後才完成。

在目標執行緒上，可以透過兩種方式執行佇列中的工作。首先，使用者可以明確呼叫 emscripten_proxy_execute_queue 來執行已針對目前執行緒排隊的任何工作。或者，如果目標執行緒返回 JS 事件迴圈，則會自動執行佇列中的工作，例如透過 emscripten_exit_with_live_runtime。

如需如何使用代理 API 的範例，請參閱 test_pthread_proxying.c 和 test_pthread_proxying_cpp.cpp。

API 參考

類型

em_proxying_queue

指向一組執行緒本機工作佇列 (每個執行緒一個) 的不透明控制代碼，可以從其他執行緒非同步或同步代理工作。

代理工作只能在即時執行緒執行階段完成，因此使用者必須確保在執行緒退出之前完成所有代理工作，或者執行緒透過即時執行階段退出，例如透過 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 代理回去。這三個函式都將接收相同的引數 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 代理回去。這三個函式都將接收相同的引數 arg。如果 func 成功加入佇列並通知目標執行緒，則回傳 1，否則回傳 0。

C++ API

當使用 C++11 或更新版本編譯時，此 C++ API 由 proxying.h 提供。它定義於命名空間 emscripten 內。

類型ProxyingQueue

一個 em_proxying_queue* 的精簡 C++ 包裝器。

類型ProxyingCtx

一個 em_proxying_ctx* 的精簡 C++ 包裝器。

em_proxying_ctx *ctx

包裝的 em_proxying_ctx*。

void finish()

在包裝的 em_proxying_ctx* 上呼叫 emscripten_proxy_finish。

void execute()

在包裝的 em_proxying_queue* 上呼叫 emscripten_proxy_execute_queue。

bool proxyAsync(pthread_t target, std::function<void()> &&func)

呼叫 emscripten_proxy_async 來執行 func，如果函式成功加入佇列，則回傳 true，否則回傳 false。

bool proxySync(const pthread_t target, const std::function<void()> &func)

呼叫 emscripten_proxy_sync 來執行 func，如果函式成功完成，則回傳 true，否則回傳 false。

bool proxySyncWithCtx(const pthread_t target, const std::function<void(ProxyingCtx)> &func)

呼叫 emscripten_proxy_sync_with_ctx 來執行 func，如果函式成功透過 emscripten_proxy_finish 或 ProxyingCtx::finish 標示為完成，則回傳 true，否則回傳 false。

bool proxyCallback(pthread_t target, std::function<void()> &&funcstd::function<void()> &&callbackstd::function<void()> &&cancel)

呼叫 emscripten_proxy_callback 來執行 func 並排程 callback 或 cancel，如果函式成功加入佇列，則回傳 true，否則回傳 false。

bool proxyCallbackWithCtx(pthread_t target, std::function<void(ProxyingCtx)> &&func, std::function<void()> &&callbackstd::function<void()> &&cancel)

呼叫 emscripten_proxy_callback_with_ctx 來執行 func 並排程 callback 或 cancel，如果函式成功加入佇列，則回傳 true，否則回傳 false。