Simplify execution model to worker + owngil modes (v3.0.0)

[benoitc]

Summary

This is the preparation for the v3.0.0 release. The public surface gets smaller, while the internals are reorganized around per-context worker pthreads.

The set of public modes is now worker | owngil. Other atoms like subinterp, auto, multi_executor or free_threaded are no longer accepted. The NIF boundary validates the mode strictly and returns {error, {invalid_mode, _}} for anything else, which closes a small loophole where py_reactor_context used to silently fall back to worker.

A few APIs that did not really earn their keep have been removed: py:num_executors/0, py:async_stream/3,4, and the entire py:subinterp_* family of explicit handles. For OWN_GIL parallelism, the path is now py_context:new(#{mode => owngil}), which gives the same isolation with proper OTP supervision. The num_executors and num_async_workers config keys are gone too, since they were already no-ops, and the legacy py_async_pool gen_server with them.

On the async side, two things were genuinely broken and are now fixed. py:async_call/3,4 followed by py:async_await/1,2 used to time out silently, because the await was listening for the wrong message tag. And py:async_gather/1,2 simply returned gather_not_implemented. Both round-trip correctly now, on top of py_event_loop.

The architectural change underneath is that each context owns its dedicated pthread, with stable thread affinity. This is what we needed to make numpy, torch and tensorflow happy with their thread-local state. The multi-executor pool, the subinterpreter pool, and the various legacy scaffolds that used to live alongside are gone.

For Python 3.14+, we no longer install the deprecated global asyncio.set_event_loop_policy. The two recommended entry points, erlang.run(main) and asyncio.Runner(loop_factory=erlang.new_event_loop), do not need it and work on every supported version from 3.9 to 3.14+. The legacy erlang.install() helper now raises a RuntimeError on 3.14+ with a small message pointing at those alternatives. On 3.12-3.13 it still works, with a DeprecationWarning you can suppress per call via erlang.install(silent=True) if you knowingly stick to the legacy pattern.

Review-driven fixes

A second round of review surfaced four issues that have all been addressed:

• A potential use-after-free on shutdown timeout: when a worker pthread was stuck in long-running Python, the 30-second join would fail, the helper returned, and the BEAM later freed the resource memory under the still-running thread. We now pin the resource via enif_keep_resource on the leak path so its memory survives the stuck thread; the callback pipes are kept open with it for the same reason. We also dropped the CTX_REQ_SHUTDOWN sentinel (which could be orphaned in the queue if the worker exited mid-loop) in favor of a direct pthread_cond_broadcast.
• Stale {py_result, _, _} messages were piling up on the context process whenever wait_for_async_result/2 timed out (the worker can still finish later and deliver the result). A small drain now runs before the matching receive, keeping the mailbox bounded. Pinned by a new CT case that injects a fake stale result and checks the mailbox is empty after the next call.
• ctx_request_create did not check the returns of pthread_mutex_init, pthread_cond_init and enif_alloc_env. Under resource pressure that could segfault on the first enif_make_copy of a NULL request env. The function now rolls back partial state on any init failure; all 14 call sites already test the result.
• A small bit of dead code went out: the _ErlangChildWatcher class on the Python side, which was never instantiated, and a couple of stale "for now" comments on the SharedDict path that no longer reflected the design.

Long-running env calls

The env-bearing call, eval and exec paths used to take a synchronous dispatch with a 30-second pthread_cond_timedwait deadline. Long Python work would return {error, worker_timeout} while the worker kept going, and the eventual result would be lost. The non-env paths had already moved to async dispatch, so we just had to add the env variants on top. Three new NIFs wrap the existing async dispatch with the local env threaded through, and the Erlang side falls back to the blocking NIF only when the worker thread isn't available. The worker_timeout error is no longer reachable on the env path.

Tests and verification

The test suite now has dedicated coverage for thread affinity, the asyncio policy gate on 3.14+, the stale-result drain, and the env-async dispatch path. On Python 3.14 the final tally is 529 passed, 5 user-skipped, 0 failed, with py_async_e2e_SUITE and py_udp_e2e_SUITE both at 10/10 and no deprecation warnings during init.

The user-facing docs (README, getting-started, scalability, migration, owngil_internals, process-bound-envs, reactor, preload, testing-free-threading, asyncio) have been refreshed to remove dead snippets and stale mode names. The erlang.sleep behavior table has been rewritten to match the v3.0 worker-pthread architecture rather than the older "dirty scheduler released in all sync contexts" framing. The migration guide intentionally keeps the historical references, so users coming from v1.8 or v2.0 can still find their way.

Net delta versus v2.3.1: about 1,000 lines removed.