feat(async): event-loop async support — fd primitive, adapters, native Swoole, shared reactor

[CodeLieutenant]

Implements #24 — makes the driver usable inside non-blocking PHP event loops instead of only blocking on Future::get().

The C driver resolves futures on its own IO thread(s); this exposes that completion to userland so any loop can await a query without blocking. get() stays blocking, so existing sync code is unaffected and pays nothing.

What's in it

1. Core primitive (C) — works with any loop, zero deps
Every Future gains:

$future->getResource(): resource   // readable once the future resolves
$future->isReady(): bool

getResource() returns a php_stream that becomes readable exactly once when the driver resolves the future (via cass_future_set_callback + a self-pipe). Watch it with stream_select/ReactPHP/AMPHP/Swoole; on readable, get() returns without blocking. Linux uses eventfd (1 syscall, 1 fd, no SIGPIPE); macOS falls back to a pipe. src/FutureNotifier.{c,h}.

2. Framework adapters (lib/Async/, optional peer deps — require-dev + suggest)
Revolt (fiber await, the default), Amp (toFuture), ReactPhp (toPromise), Swoole (coroutine waitEvent).

3. Native Swoole/OpenSwoole — opt-in build flag
-DPHP_SCYLLADB_ENABLE_SWOOLE / _OPENSWOOLE (+ -DPHP_SCYLLADB_SWOOLE_SRC=…) compiles one small C++ shim (src/Async/SwooleBridge.cc) so Future::get() suspends the current coroutine instead of blocking. Default build stays pure C; swoole symbols resolve lazily at runtime.

4. Shared reactor — opt-in, O(1) fds for high fan-out
Cassandra\Async\Reactor (::add/resource/poll/pending): one eventfd + a mutex-guarded MPSC completion queue shared across many futures, so the loop watches one fd regardless of concurrency. Per-future fds cap out at FD_SETSIZE (~512 on macOS); the reactor scales to thousands and is even a touch faster at matched fan-out. lib/Async/ReactorRevolt.php adapter. See docs/async.md.

Testing

• tests/Feature/Async/* against live ScyllaDB: primitive (stream_select multiplexing, error propagation, early-free SIGPIPE regression), Revolt/Amp/React (concurrency), Swoole (skip-guarded), reactor (io_threads=4 multi-producer, errors, model-mixing guards, Revolt adapter). All green; full suite 880 passed.
• Benchmarks benchmarks/Live/{AsyncBench,ReactorBench}.php + committed baselines under benchmarks/baselines/ (JSON + Markdown, via composer bench:baseline:export).
• fd/mem leak checks clean; two adversarial cross-thread C reviews (the reactor one caught + fixed a narrow-window UAF — signal now under the lock).

Notes for reviewers

• Draft because two things want CI/hardware this environment lacks:
  • Native Swoole path: the flag-off default build + the C++ shim compile-check against real swoole-src are verified here, but the runtime coroutine behavior needs an actual (Open)Swoole runtime (not installed locally). Its tests are skip-guarded.
  • Reactor cross-thread code: local macOS ASan doesn't instrument cleanly, so the Linux CI ASan job is the authoritative race gate (covered locally by the adversarial review + the io_threads=4 stress + leak checks).
• Generated *_arginfo.h / *_descriptor.c are build-time artifacts (git-ignored), regenerated from the committed stubs.
• The one pre-existing full-suite failure (UuidTest › unique UUIDs across separate processes) is environmental — it spawns php -d extension=cassandra children by bare name and passes in CI where the extension is installed.

🤖 Generated with Claude Code