feat: per-request cache for frankenphp_get_vars

Ninth step on top of #2287's split. Adds a C-side per-request cache
keyed on the background worker's vars version so repeated get_vars
reads within one request run at O(1) and return the same HashTable
pointer.

- __thread HashTable *bg_vars_cache maps worker name -> { version,
  cached_zval }. Initialized lazily on first get_vars call per
  request. Destroyed before php_request_shutdown tears down request
  memory, so the cached zvals are torn down while their backing
  request-memory structures are still alive.

- go_frankenphp_get_vars grew callerVersion / outVersion out-params:
  - If callerVersion matches the live varsVersion, Go skips the deep
    copy entirely and only reports outVersion. The C side reuses its
    cached zval (with ZVAL_COPY for refcount bump).
  - If versions differ, Go runs the normal copy-under-RLock path and
    reports the fresh version for the caller to cache.

- PHP_FUNCTION(frankenphp_get_vars) consults the cache before calling
  Go, then either reuses the cached zval (hit) or stores the fresh
  copy (miss). Identity is preserved: $vars === $prev_vars holds
  across reads within one request.

- TestGetVarsCacheIdentity: two reads in one request return the same
  zval (=== true).
- TestGetVarsCacheManyReads: 500 reads in one script complete without
  memory corruption, proving the cache tear-down at request end is
  correct.

All 16 existing bg worker tests still pass.

Author: nicolas-grekas

bgworker.go

@@ -462,12 +462,19 @@ func go_frankenphp_set_vars(threadIndex C.uintptr_t, varsPtr unsafe.Pointer, old
 }
 
 // go_frankenphp_get_vars resolves the named worker through the lookup
-// (named or catch-all), checks its sk.ready without starting the worker,
-// and copies its vars into the return value. If the caller hasn't called
+// (named or catch-all), checks sk.ready without starting the worker, and
+// copies its vars into the return value. If the caller hasn't called
 // ensure() first, this returns a "not ready" error.
 //
+// callerVersion / outVersion implement a per-request cache:
+//   - If callerVersion is non-nil and equals the current varsVersion,
+//     the copy is skipped; outVersion is still set so the C side can
+//     reuse its cached zval with pointer equality.
+//   - Otherwise returnValue receives a fresh deep copy and outVersion
+//     reports the version that copy corresponds to.
+//
 //export go_frankenphp_get_vars
-func go_frankenphp_get_vars(threadIndex C.uintptr_t, name *C.char, nameLen C.size_t, returnValue *C.zval) *C.char {
+func go_frankenphp_get_vars(threadIndex C.uintptr_t, name *C.char, nameLen C.size_t, returnValue *C.zval, callerVersion *C.uint64_t, outVersion *C.uint64_t) *C.char {
 	thread := phpThreads[threadIndex]
 	lookup := getLookup(thread)
 	if lookup == nil {
@@ -493,8 +500,21 @@ func go_frankenphp_get_vars(threadIndex C.uintptr_t, name *C.char, nameLen C.siz
 		return C.CString("background worker not ready: " + goName + " (no set_vars call yet)")
 	}
 
+	// Fast path: caller's cached version matches current. Skip the copy;
+	// the caller will reuse its cached zval.
+	if callerVersion != nil && outVersion != nil {
+		v := sk.varsVersion.Load()
+		*outVersion = C.uint64_t(v)
+		if uint64(*callerVersion) == v {
+			return nil
+		}
+	}
+
 	sk.mu.RLock()
 	C.frankenphp_copy_persistent_vars(returnValue, sk.varsPtr)
+	if outVersion != nil {
+		*outVersion = C.uint64_t(sk.varsVersion.Load())
+	}
 	sk.mu.RUnlock()
 
 	return nil

bgworkercache_test.go

@@ -0,0 +1,56 @@
+package frankenphp_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestGetVarsCacheIdentity verifies that two get_vars calls within one
+// request return the *same* zval (pointer identity via ===) when the
+// worker hasn't published a new version in between. This is the user-
+// visible guarantee that proves the per-request cache is wired.
+func TestGetVarsCacheIdentity(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("cache-worker", "testdata/background-worker-cache-fixture.php", 1,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
+	)
+
+	body := serveBody(t, testDataDir, "background-worker-cache-identity.php")
+	assert.Contains(t, body, "first=cached-value")
+	assert.Contains(t, body, "second=cached-value")
+	assert.Contains(t, body, "identical=true", "cached zvals must be === across repeated reads:\n"+body)
+}
+
+// TestGetVarsCacheManyReads exercises the cache path under load: one
+// request calls get_vars 500 times against a nested-array worker. The
+// second call onward is a cache hit; the test just asserts the script
+// completes without corruption.
+func TestGetVarsCacheManyReads(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("cache-worker", "testdata/background-worker-cache-fixture.php", 1,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
+	)
+
+	// ensure() first so the eager-start race doesn't surface before the
+	// 500-read loop even begins.
+	php := `<?php
+frankenphp_ensure_background_worker('cache-worker');
+for ($i = 0; $i < 500; $i++) {
+    $vars = frankenphp_get_vars('cache-worker');
+}
+echo 'ok=', $vars['marker'] ?? 'MISSING', "\n";`
+	tmp := testDataDir + "bg-cache-many.php"
+	require.NoError(t, os.WriteFile(tmp, []byte(php), 0644))
+	t.Cleanup(func() { _ = os.Remove(tmp) })
+
+	body := serveBody(t, testDataDir, "bg-cache-many.php")
+	assert.Contains(t, body, "ok=cached-value", "500 cached reads should all succeed:\n"+body)
+	assert.False(t, strings.Contains(body, "Fatal error") || strings.Contains(body, "corrupted"), "no corruption expected:\n"+body)
+}

frankenphp.c

@@ -93,6 +93,31 @@ __thread php_stream *worker_signaling_stream = NULL;
 __thread char *captured_last_php_error = NULL;
 __thread HashTable *sandboxed_env = NULL;
 
+/* Per-thread cache for frankenphp_get_vars results. Maps worker name to
+ * { version, cached_zval }. When the Go side reports the version hasn't
+ * changed, the cached zval is returned with a refcount bump, giving the
+ * PHP caller the same HashTable pointer so repeated reads within a
+ * request run at O(1) without walking persistent memory every time. */
+typedef struct {
+  uint64_t version;
+  zval value;
+} bg_vars_cache_entry;
+__thread HashTable *bg_vars_cache = NULL;
+
+static void bg_vars_cache_dtor(zval *zv) {
+  bg_vars_cache_entry *entry = Z_PTR_P(zv);
+  zval_ptr_dtor(&entry->value);
+  free(entry);
+}
+
+static void bg_vars_cache_reset(void) {
+  if (bg_vars_cache) {
+    zend_hash_destroy(bg_vars_cache);
+    free(bg_vars_cache);
+    bg_vars_cache = NULL;
+  }
+}
+
 #ifndef PHP_WIN32
 static bool is_forked_child = false;
 static void frankenphp_fork_child(void) { is_forked_child = true; }
@@ -996,13 +1021,48 @@ PHP_FUNCTION(frankenphp_get_vars) {
   Z_PARAM_STR(name);
   ZEND_PARSE_PARAMETERS_END();
 
-  char *error = go_frankenphp_get_vars(thread_index, (char *)ZSTR_VAL(name),
-                                       ZSTR_LEN(name), return_value);
+  /* Look up a cached entry first so Go can short-circuit the copy when
+   * the background worker has not changed its vars since we last read
+   * them. On a cache hit we reuse the same zval, so $vars === $prev_vars
+   * holds across repeated reads within one request. */
+  uint64_t caller_version = 0;
+  uint64_t out_version = 0;
+  bg_vars_cache_entry *cached = NULL;
+  if (bg_vars_cache) {
+    zval *entry_zv = zend_hash_find(bg_vars_cache, name);
+    if (entry_zv) {
+      cached = Z_PTR_P(entry_zv);
+      caller_version = cached->version;
+    }
+  }
+
+  char *error = go_frankenphp_get_vars(
+      thread_index, (char *)ZSTR_VAL(name), ZSTR_LEN(name), return_value,
+      cached ? &caller_version : NULL, &out_version);
   if (error) {
     zend_throw_exception(spl_ce_RuntimeException, error, 0);
     free(error);
     RETURN_THROWS();
   }
+
+  if (cached && out_version == caller_version) {
+    /* Cache hit: Go skipped the copy. Return the cached zval. */
+    ZVAL_COPY(return_value, &cached->value);
+    return;
+  }
+
+  /* Cache miss: store the fresh copy so subsequent reads within this
+   * request can be served without walking persistent memory. */
+  if (!bg_vars_cache) {
+    bg_vars_cache = malloc(sizeof(HashTable));
+    zend_hash_init(bg_vars_cache, 4, NULL, bg_vars_cache_dtor, 1);
+  }
+  bg_vars_cache_entry *entry = malloc(sizeof(*entry));
+  entry->version = out_version;
+  ZVAL_COPY(&entry->value, return_value);
+  zval entry_zv;
+  ZVAL_PTR(&entry_zv, entry);
+  zend_hash_update(bg_vars_cache, name, &entry_zv);
 }
 
 PHP_FUNCTION(frankenphp_ensure_background_worker) {
@@ -1655,6 +1715,11 @@ static void *php_thread(void *arg) {
        * so background-worker boot failures can surface the cause. */
       frankenphp_capture_last_php_error();
 
+      /* Invalidate the per-request get_vars cache before php_request_shutdown
+       * tears down request memory: the cached zvals live in request memory
+       * and can't be freed after shutdown runs. */
+      bg_vars_cache_reset();
+
       /* shutdown the request, potential bailout to zend_catch */
       php_request_shutdown((void *)0);
       frankenphp_free_request_context();
@@ -1674,6 +1739,7 @@ static void *php_thread(void *arg) {
     if (!has_attempted_shutdown) {
       /* php_request_shutdown() was not called, force a shutdown now */
       reset_sandboxed_environment();
+      bg_vars_cache_reset();
       zend_try { php_request_shutdown((void *)0); }
       zend_catch {}
       zend_end_try();

testdata/background-worker-cache-fixture.php

@@ -0,0 +1,20 @@
+<?php
+
+// Long-lived bg worker: disable PHP max_execution_time so the 30s default
+// cannot interrupt the stream_select park. The C side calls
+// zend_unset_timeout() too, but the belt-and-suspenders here covers PHP
+// builds where that path does not fully disarm the timer.
+set_time_limit(0);
+
+// Stable bg worker: publishes one snapshot and never updates.
+frankenphp_set_vars([
+    'marker' => 'cached-value',
+]);
+
+$stream = frankenphp_get_worker_handle();
+if ($stream !== null) {
+    $read = [$stream];
+    $write = null;
+    $except = null;
+    stream_select($read, $write, $except, null);
+}

testdata/background-worker-cache-identity.php

@@ -0,0 +1,14 @@
+<?php
+
+// Calls get_vars twice within one request. The cache guarantees pointer
+// identity: the two zvals should be === (same HashTable pointer) because
+// the underlying worker hasn't published a new version in between.
+// ensure() waits for the bg worker's first set_vars so eager-start races
+// don't surface before the cache path is exercised.
+frankenphp_ensure_background_worker('cache-worker');
+$first = frankenphp_get_vars('cache-worker');
+$second = frankenphp_get_vars('cache-worker');
+
+echo 'first=', isset($first['marker']) ? $first['marker'] : 'MISSING', "\n";
+echo 'second=', isset($second['marker']) ? $second['marker'] : 'MISSING', "\n";
+echo 'identical=', ($first === $second) ? 'true' : 'false', "\n";