Add emscripten_proxy_fd_with_ctx and 'fd' async variants for JS library functions

[guybedford]

Adds the _fd variant alongside the _promise and _callback variants of #27880 / #27954, so the result of an asynchronous JS library function can be awaited through poll/select/epoll from any stack, alongside sockets and other descriptors. It is built on a new proxying primitive.

emscripten_proxy_fd_with_ctx(q, target, func, arg) proxies a task and returns a file descriptor that becomes readable once the task calls emscripten_proxy_finish / emscripten_proxy_finish_result (readable with POLLERR if it fails or is cancelled), so proxied work can be waited on with the usual descriptor APIs. read() of an intptr_t yields the result (EIO on failure) and the fd is then at EOF. It is a new FD context kind alongside sync and callback: finishing settles the fd directly on the target thread, with nothing proxied back. Descriptors live on the main thread, which is the only supported target for now, so the calling thread may be blocked polling the fd; with WasmFS pollable descriptors the same API will be able to target any thread.

Since an fd has no then through which the task's arg could hand the result over, proxying.h also gains emscripten_proxy_finish_result(ctx, void*) (the fd is readable with it; the promise of emscripten_proxy_promise_with_ctx is fulfilled with it, where it was always NULL) and emscripten_proxy_fail(ctx) (the fd is readable with POLLERR; the promise is rejected, or the cancel callback of emscripten_proxy_callback_with_ctx runs, as if the target thread had exited).

foo_fd(), listed as __async: ['fd'], runs the same body (with sync always false). From a pthread it is emscripten_proxy_fd_with_ctx of the main-thread body, finished with emscripten_proxy_finish_result. On the main thread the body's value or Promise settles the fd directly, so a synchronous completion is readable on return. read() of an intptr_t takes the value (0 for a void function, EIO if the Promise rejected); the fd is then at EOF and must be closed. It is a link-time error under WASMFS, which has no readiness layer. As with the other variants, it is emitted only where used.

int lookup_fd(const char* name);

Tests: test_pthread_proxying covers emscripten_proxy_fd_with_ctx, emscripten_proxy_finish_result and emscripten_proxy_fail; jslib.test_jslib_async_auto_variants_fd in plain, ASYNCIFY, JSPI and PROXY_TO_PTHREAD builds, wasm32 and wasm64; test_jslib_async_auto_variants_fd_wasmfs.

Made with AI assistance under my review

[tlively]

It looks like this implementation works by proxying not just the library function, but also a wrapper fdFromPromise call that produces an FD that can be polled for the result of the promise. This makes sense because currently (without WasmFS support for general pollable FDs), FDs can only be created on the main thread, where the FS lives.

I don't think that's general enough, though. JS library functions proxied to the main thread are only one special case of proxied work that a thread might be waiting on. The advantage of using pollable fds is that a thread can synchronously wait on many pending tasks at once, but that only works if all the pending tasks can be represented as fds. If the JS library proxying were built on a lower-level emscripten_proxy_fd_with_ctx, then all tasks proxied via em_proxying_queue would be compatible with epoll, no matter what queue or thread they run on.

Without WasmFS support for pollable FDs, emscripten_proxy_fd_with_ctx targeting any thread other than the main thread will have to trampoline through the main thread to allocate an FD, then do a promise or callback proxy call from the main thread to the target thread to arrange for the FD to become ready when the work is done.

Once we have WasmFS support, though, emscripten_proxy_fd_with_ctx will be able to allocate an FD directly, then proxy directly to the target thread, which will be able to mark the FD ready without having to proxy anything back to the calling thread.

[guybedford]

Once we have WasmFS support, though, emscripten_proxy_fd_with_ctx will be able to allocate an FD directly, then proxy directly to the target thread, which will be able to mark the FD ready without having to proxy anything back to the calling thread.

Completely agreed on this overall direction, and I think that sounds like a sensible refactoring later on, that has no public surface area at risk from this current approach for now.

[tlively]

How about implementing emscripten_proxy_fd_with_ctx, but only with support for proxying to the main thread for now? That hopefully strikes a good balance between going in the direction we want for the long term and not adding extra complexity to the critical path.

[guybedford]

I went ahead and added emscripten_proxy_fd_with_ctx as described with the main thread as the only supported target by assertion for now, which could then extend to WasmFS support in future to support arbitrary threads.

[tlively]

Oh, I see. Because there's no equivalent of promise.then() for pollable fds, there's no way to chain on an extraction of the result from the arg the way you can with promises. Given that, I would support adding something like emscripten_proxy_finish_result for use with both promises (if feasible) and fds. It would be nice to do that in a separate PR, either before or after this one.

[guybedford]

Ok I've gone ahead and reinstated the emscripten_proxy_finish_result style approach in the base PR at #27880. Please take another look there further.

[guybedford]

Since it's still not clear if this one will land, I've instead moved the emscripten_proxy_finish_result back into this PR directly, so it doesn't affect the lower stack PR unnecessarily.