Add non-blocking future support (fdb_future_set_callback, awaitAll, range read-ahead)

[s2x]

Description

fdb_future_set_callback is not bound in NativeClient.php, so every future in this library is strictly blocking: Future::await() calls fdb_future_block_until_ready() and the calling thread stops.

This is the largest structural gap against the other bindings. Java resolves futures into CompletableFuture and exposes AsyncIterable for ranges; Go resolves them on goroutines. In PHP today:

• there is no way to fan out N reads and wait for them together — the caller can construct several FutureValue objects before awaiting, but nothing prefetches or waits on them as a group;
• RangeResult fetches page N+1 only after page N has been fully consumed, with no read-ahead (Java's AsyncIterable overlaps them);
• the library cannot be driven from a Fiber-based event loop (Revolt/AMPHP/ReactPHP) or from Swoole without blocking the loop.

What needs to be done

1. Bind the callback entry point:

   fdb_error_t fdb_future_set_callback(FDBFuture* f, FDBCallback callback, void* callback_parameter);

   Note that the callback fires on an FDB network thread. With setCallbacksOnExternalThreads() disabled this is the client's network thread, and PHP code cannot safely run there — so the callback must only flip a flag/write to a self-pipe, with the actual resolution happening on the PHP thread.

2. Add to Future:

   • onReady(callable $fn): void — register a completion hook
   • a non-blocking poll path built on the already-bound fdb_future_is_ready

3. Add a group-await helper, e.g. Future::awaitAll(array $futures): array, that polls/waits across futures instead of serializing them.

4. Add read-ahead to RangeResult::getIterator(): issue the request for the next chunk before yielding the current chunk's last item.

5. Optional follow-up (separate issue if it grows): a Fiber-aware await() that suspends the current Fiber instead of blocking, so the library composes with Revolt-based event loops.

Notes

• Step 4 alone (read-ahead) delivers most of the practical win for typical range scans and does not require the callback binding — it can land first.
• Thread-safety at the FFI boundary is the risky part; a self-pipe or an atomic flag checked from PHP is the conservative design.

Acceptance Criteria

• Future::awaitAll() resolves N futures with roughly one round trip's latency, not N
• RangeResult prefetches the next chunk while the current one is being consumed
• No PHP code executes on the FDB network thread
• Benchmarks/tests demonstrating the parallel-read and read-ahead improvements
• docs/advanced.md documents the async model and its limits
• composer lint and composer test clean

[s2x]

First slice implemented in #109 (squash-merge pending review):

• Future::awaitAll() + Future::onReady() — group await and a PHP-thread completion hook. fdb_future_set_callback remains deliberately unbound (callback fires on the FDB network thread where PHP is unsafe).
• RangeResult read-ahead — the next chunk request is issued before the current chunk's items are yielded; never fetches past an explicit limit.
• Unit tests (compiled stub lib) + live-cluster integration tests; composer lint and composer test clean.
• docs/advanced.md documents the async model; changelog entries added.

Still open on this issue: Fiber-aware await() (Revolt/Swoole integration) and, if ever proven necessary, a safe callback binding via self-pipe/atomic flag.

[s2x]

Implemented in #111 (squash-merge pending review).

What landed:

• Future::awaitAll() — grouped wait over N futures via the already-bound non-blocking fdb_future_is_ready() (1 ms spin); results/errors resolved in input order. No PHP code ever runs on the FDB network thread.
• Future::onReady() — completion hook firing once on the PHP thread, just before the payload is read.
• Range read-ahead — RangeResult::paginate() now issues page N+1 before page N is fully consumed (getIterator() passes the un-awaited future to the paginator; new KvsFuture interface keeps existing fetchers compatible).
• docs/advanced.md documents the async model and its limits; CHANGELOG.md has a [#92] entry.

Deliberately deferred to a follow-up: the fdb_future_set_callback binding itself (PHP closures cannot safely run on the FDB network thread; needs a C-level self-pipe/flag design). Grouped waits + read-ahead deliver the practical parallelism win without it. A Fiber-aware await() remains open as the issue's optional step 5.