proxying.h

The Emscriptenproxying.hAPI provides a mechanism for dispatching work to be executed by a target threadand optionally blocking until that work has been completed. This is particularlyuseful in a Web context where certain JS APIs can only be called on particularthreads; any thread can access those APIs by proxying the API calls to thecorrect threads. Proxying is also useful for wrapping asynchronous JS tasks witha synchronous interface. The calling thread can proxy the asynchronous task to adedicated worker thread and wait until the worker thread eventually marks thetask as complete, possibly after returning multiple times to the JS event loop.

On the target thread, queued work can be executed in two ways. First, the usermay explicitly callemscripten_proxy_execute_queue to execute any tasks thathave been queued for the current thread. Alternatively, queued work will executeautomatically if the target thread returns to the JS event loop, for example viaemscripten_exit_with_live_runtime.

Seetest_pthread_proxying.c andtest_pthread_proxying_cpp.cpp for examplesof how to use the proxying API.

API Reference

Types

typeem_proxying_queue

An opaque handle to a set of thread-local work queues (one per thread) towhich work can be asynchronously or synchronously proxied from other threads.

Proxied work can only be completed on live thread runtimes, so users mustensure either that all proxied work is completed before a thread exits or thatthe thread exits with a live runtime, e.g. viaemscripten_exit_with_live_runtime to avoid dropped work.

typeem_proxying_ctx

An opaque handle to a currently-executing proxied task, used to signal the endof the task.

Functions

em_proxying_queue*em_proxying_queue_create()

Allocate a new proxying queue.

voidem_proxying_queue_destroy(em_proxying_queue*q)

Free a proxying queue. The queue should not have any remaining queued work.

em_proxying_queue*emscripten_proxy_get_system_queue()

Get the queue used for proxying low-level runtime work. Work on this queue maybe processed at any time inside system functions, so it must be nonblockingand safe to run at any time, similar to a native signal handler. User codeshould generally not use this function.

voidemscripten_proxy_execute_queue(em_proxying_queue*q)

Execute all the tasks enqueued for the current thread on the given queue. Newtasks that are enqueued concurrently with this execution will be executed aswell. This function returns once it observes an empty queue.

voidemscripten_proxy_finish(em_proxying_ctx*ctx)

Signal the end of a task proxied withemscripten_proxy_sync_with_ctx.

intemscripten_proxy_async(em_proxying_queue*q,pthread_ttarget_thread,void(*func)(void*),void*arg)

Enqueuefunc to be called with argumentarg on the given queue andthread then return immediately without waiting forfunc to be executed.Returns 1 if the work was successfully enqueued or 0 otherwise.

intemscripten_proxy_sync(em_proxying_queue*q,pthread_ttarget_thread,void(*func)(void*),void*arg)

Enqueuefunc to be called with argumentarg on the given queue andthread then wait forfunc to be executed synchronously before returning.Returns 1 if thefunc was successfully completed and 0 otherwise,including if the target thread is canceled or exits before the work iscompleted.

intemscripten_proxy_sync_with_ctx(em_proxying_queue*q,pthread_ttarget_thread,void(*func)(em_proxying_ctx*,void*),void*arg)

The same asemscripten_proxy_sync except that instead of waiting for theproxied function to return, it waits for the proxied task to be explicitlymarked finished withemscripten_proxy_finish.func need not callemscripten_proxy_finish itself; it could instead store the context pointerand callemscripten_proxy_finish at an arbitrary later time.

intemscripten_proxy_callback(em_proxying_queue*q,pthread_ttarget_thread,void(*func)(void*),void(*callback)(void*),void(*cancel)(void*),void*arg)

Enqueuefunc on the given queue and thread. Once (and if) it finishesexecuting, it will asynchronously proxycallback back to the currentthread on the same queue, or if the target thread dies before the work can becompleted,cancel will be proxied back instead. All three function willreceive the same argument,arg. Returns 1 iffunc was successfullyenqueued and the target thread notified or 0 otherwise.

intemscripten_proxy_callback_with_ctx(em_proxying_queue*q,pthread_ttarget_thread,void(*func)(em_proxying_ctx*,void*),void(*callback)(void*),void(*cancel)(void*),void*arg)

Enqueuefunc on the given queue and thread. Once (and if) it finishes thetask by callingemscripten_proxy_finish on the givenem_proxying_ctx,it will asynchronously proxycallback back to the current thread on thesame queue, or if the target thread dies before the work can be completed,cancel will be proxied back instead. All three function will receive thesame argument,arg. Returns 1 iffunc was successfully enqueued andthe target thread notified or 0 otherwise.

C++ API

This C++ API is provided by proxying.h when compiling with C++11 or later. It isdefined within namespaceemscripten.

typeProxyingQueue

A thin C++ wrapper around anem_proxying_queue*.

typeProxyingCtx

A thin C++ wrapper around anem_proxying_ctx*.

em_proxying_ctx*ctx

The wrappedem_proxying_ctx*.

voidfinish()

Callsemscripten_proxy_finish on the wrappedem_proxying_ctx*.

voidexecute()

Callsemscripten_proxy_execute_queue on the wrappedem_proxying_queue*.

boolproxyAsync(pthread_ttarget,std::function<void()>&&func)

Callsemscripten_proxy_async to executefunc, returningtrue if thefunction was successfully enqueued andfalse otherwise.

boolproxySync(constpthread_ttarget,conststd::function<void()>&func)

Callsemscripten_proxy_sync to executefunc, returningtrue if thefunction was successfully completed orfalse otherwise.

boolproxySyncWithCtx(constpthread_ttarget,conststd::function<void(ProxyingCtx)>&func)

Callsemscripten_proxy_sync_with_ctx to executefunc, returningtrue if the function was successfully marked done withemscripten_proxy_finish orProxyingCtx::finish andfalseotherwise.

boolproxyCallback(pthread_ttarget,std::function<void()>&&func,std::function<void()>&&callback,std::function<void()>&&cancel)

Callsemscripten_proxy_callback to executefunc and schedule eithercallback orcancel, returningtrue if the function wassuccessfully enqueued andfalse otherwise.

boolproxyCallbackWithCtx(pthread_ttarget,std::function<void(ProxyingCtx)>&&func,std::function<void()>&&callback,std::function<void()>&&cancel)

Callsemscripten_proxy_callback_with_ctx to executefunc andschedule eithercallback orcancel, returningtrue if thefunction was successfully enqueued andfalse otherwise.