proxying.h

Die Emscripten proxying.h API bietet einen Mechanismus zum Verteilen von Arbeit, die von einem Ziel-Thread ausgeführt werden soll, und optionales Blockieren, bis diese Arbeit abgeschlossen ist. Dies ist besonders nützlich in einem Web-Kontext, wo bestimmte JS-APIs nur auf bestimmten Threads aufgerufen werden können; jeder Thread kann auf diese APIs zugreifen, indem er die API-Aufrufe an die korrekten Threads weiterleitet. Proxying ist auch nützlich, um asynchrone JS-Aufgaben mit einer synchronen Schnittstelle zu umhüllen. Der aufrufende Thread kann die asynchrone Aufgabe an einen dedizierten Worker-Thread weiterleiten und warten, bis der Worker-Thread die Aufgabe schließlich als abgeschlossen markiert, möglicherweise nachdem er mehrmals zur JS-Ereignisschleife zurückgekehrt ist.

Im Ziel-Thread kann die in der Warteschlange befindliche Arbeit auf zwei Arten ausgeführt werden. Erstens kann der Benutzer explizit emscripten_proxy_execute_queue aufrufen, um alle Aufgaben auszuführen, die für den aktuellen Thread in die Warteschlange gestellt wurden. Alternativ wird die in der Warteschlange befindliche Arbeit automatisch ausgeführt, wenn der Ziel-Thread zur JS-Ereignisschleife zurückkehrt, zum Beispiel über emscripten_exit_with_live_runtime.

Siehe test_pthread_proxying.c und test_pthread_proxying_cpp.cpp für Beispiele zur Verwendung der Proxying-API.

API-Referenz

Typen

em_proxying_queue

Ein undurchsichtiger Handle zu einem Satz von thread-lokalen Arbeitswarteschlangen (eine pro Thread), an die Arbeit asynchron oder synchron von anderen Threads weitergeleitet werden kann.

Weitergeleitete Arbeit kann nur auf Live-Thread-Runtimes abgeschlossen werden, daher müssen Benutzer sicherstellen, dass entweder alle weitergeleitete Arbeit abgeschlossen ist, bevor ein Thread beendet wird, oder dass der Thread mit einer Live-Runtime beendet wird, z.B. über emscripten_exit_with_live_runtime, um den Verlust von Arbeit zu vermeiden.

em_proxying_ctx

Ein undurchsichtiger Handle zu einer aktuell ausgeführten weitergeleiteten Aufgabe, verwendet um das Ende der Aufgabe zu signalisieren.

Funktionen

em_proxying_queue* em_proxying_queue_create()

Eine neue Proxying-Warteschlange zuweisen.

void em_proxying_queue_destroy(em_proxying_queue* q)

Eine Proxying-Warteschlange freigeben. Die Warteschlange sollte keine verbleibende in der Warteschlange befindliche Arbeit haben.

em_proxying_queue* emscripten_proxy_get_system_queue()

Die Warteschlange abrufen, die für die Weiterleitung von Low-Level-Laufzeitaufgaben verwendet wird. Arbeit in dieser Warteschlange kann jederzeit innerhalb von Systemfunktionen verarbeitet werden, daher muss sie nicht-blockierend und jederzeit sicher ausführbar sein, ähnlich einem nativen Signal-Handler. Benutzercode sollte diese Funktion im Allgemeinen nicht verwenden.

void emscripten_proxy_execute_queue(em_proxying_queue* q)

Alle für den aktuellen Thread in der gegebenen Warteschlange eingereihten Aufgaben ausführen. Neue Aufgaben, die gleichzeitig mit dieser Ausführung eingereiht werden, werden ebenfalls ausgeführt. Diese Funktion kehrt zurück, sobald sie eine leere Warteschlange feststellt.

void emscripten_proxy_finish(em_proxying_ctx* ctx)

Das Ende einer mit emscripten_proxy_sync_with_ctx weitergeleiteten Aufgabe signalisieren.

int emscripten_proxy_async(em_proxying_queue* q, pthread_t target_thread, void (*func)(void*), void* arg)

Reiht func zur Ausführung mit Argument arg in der gegebenen Warteschlange und dem gegebenen Thread ein und kehrt dann sofort zurück, ohne auf die Ausführung von func zu warten. Gibt 1 zurück, wenn die Arbeit erfolgreich eingereiht wurde, oder 0 andernfalls.

int emscripten_proxy_sync(em_proxying_queue* q, pthread_t target_thread, void (*func)(void*), void* arg)

Reiht func zur Ausführung mit Argument arg in der gegebenen Warteschlange und dem gegebenen Thread ein und wartet dann auf die synchrone Ausführung von func, bevor es zurückkehrt. Gibt 1 zurück, wenn func erfolgreich abgeschlossen wurde, und 0 andernfalls, einschließlich wenn der Ziel-Thread abgebrochen wird oder beendet wird, bevor die Arbeit abgeschlossen ist.

int emscripten_proxy_sync_with_ctx(em_proxying_queue* q, pthread_t target_thread, void (*func)(em_proxying_ctx*, void*), void* arg)

Dasselbe wie emscripten_proxy_sync, außer dass es, anstatt auf die Rückgabe der weitergeleiteten Funktion zu warten, darauf wartet, dass die weitergeleitete Aufgabe explizit mit emscripten_proxy_finish als abgeschlossen markiert wird. func muss emscripten_proxy_finish nicht selbst aufrufen; es könnte stattdessen den Kontextzeiger speichern und emscripten_proxy_finish zu einem beliebigen späteren Zeitpunkt aufrufen.

int emscripten_proxy_callback(em_proxying_queue* q, pthread_t target_thread, void (*func)(void*), void (*callback)(void*), void (*cancel)(void*), void* arg)

Reiht func in der gegebenen Warteschlange und dem Thread ein. Sobald (und falls) die Ausführung abgeschlossen ist, wird callback asynchron an den aktuellen Thread in derselben Warteschlange weitergeleitet, oder falls der Ziel-Thread stirbt, bevor die Arbeit abgeschlossen werden kann, wird stattdessen cancel weitergeleitet. Alle drei Funktionen erhalten dasselbe Argument, arg. Gibt 1 zurück, wenn func erfolgreich eingereiht und der Ziel-Thread benachrichtigt wurde, oder 0 andernfalls.

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)

Reiht func in der gegebenen Warteschlange und dem Thread ein. Sobald (und falls) die Aufgabe durch Aufrufen von emscripten_proxy_finish auf dem gegebenen em_proxying_ctx abgeschlossen ist, wird callback asynchron an den aktuellen Thread in derselben Warteschlange weitergeleitet, oder falls der Ziel-Thread stirbt, bevor die Arbeit abgeschlossen werden kann, wird stattdessen cancel weitergeleitet. Alle drei Funktionen erhalten dasselbe Argument, arg. Gibt 1 zurück, wenn func erfolgreich eingereiht und der Ziel-Thread benachrichtigt wurde, oder 0 andernfalls.

C++ API

Diese C++ API wird von proxying.h bereitgestellt, wenn mit C++11 oder höher kompiliert wird. Sie ist im Namespace emscripten definiert.

type ProxyingQueue

Ein dünner C++ Wrapper um einen em_proxying_queue*.

type ProxyingCtx

Ein dünner C++ Wrapper um einen em_proxying_ctx*.

em_proxying_ctx *ctx

Der gewrappte em_proxying_ctx*.

void finish()

Ruft emscripten_proxy_finish auf dem gewrappten em_proxying_ctx* auf.

void execute()

Ruft emscripten_proxy_execute_queue auf der gewrappten em_proxying_queue* auf.

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

Ruft emscripten_proxy_async auf, um func auszuführen, und gibt true zurück, wenn die Funktion erfolgreich in die Warteschlange gestellt wurde, und false andernfalls.

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

Ruft emscripten_proxy_sync auf, um func auszuführen, und gibt true zurück, wenn die Funktion erfolgreich abgeschlossen wurde, oder false andernfalls.

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

Ruft emscripten_proxy_sync_with_ctx auf, um func auszuführen, und gibt true zurück, wenn die Funktion erfolgreich mit emscripten_proxy_finish oder ProxyingCtx::finish als abgeschlossen markiert wurde, oder false andernfalls.

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

Ruft emscripten_proxy_callback auf, um func auszuführen und entweder callback oder cancel zu planen, und gibt true zurück, wenn die Funktion erfolgreich in die Warteschlange gestellt wurde, und false andernfalls.

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

Ruft emscripten_proxy_callback_with_ctx auf, um func auszuführen und entweder callback oder cancel zu planen, und gibt true zurück, wenn die Funktion erfolgreich in die Warteschlange gestellt wurde, und false andernfalls.