Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01JkYTqsvYu6AYr9yQ3Q4Nt6
10 KiB
Cryo in JumPHP
ext-cryo is linked statically into JumPHP's WebAssembly engine
(docker/ext/cryo, copied from PhpCryo by tools/sync-jumphp.sh). In a game or an application it gives: snapshots
of the PHP heap (memory leaks), their reading (CryoReader), hot rewriting of code (Cryo\Engine),
metrics, and sandboxes: PHP code isolated in another PHP instance, which can neither crash nor freeze the game.
To start, with short examples (a key to take a memory picture, finding a leak, a player's code in a sandbox, waiting
for several results, a flag read at every frame, changing a rule while the game runs): https://jumphp.net/docs/cryo.
The complete guide of the extension (freezing a script and resuming it elsewhere, fork, metrics, security…):
php-cryo, docs/guide/ (French), and
13 command-line examples: examples/. This page
describes how it works in detail. Français : cryo.fr.md.
Snapshots and CryoReader
cryo_snapshot(sys_get_temp_dir() . '/a.cryo', ['redact' => ['password']]); // object graph, roots, orphans
$r = CryoReader::open(sys_get_temp_dir() . '/a.cryo');
$r->top('class', 10); // what takes the memory
$r->dominators(10); // what RETAINS the memory
$r->path($id); // root -> ... -> the object
cryo_roots_of($obj); // live, without a file: what keeps this object alive?
In the browser the file is written to emscripten's file system (/tmp), or to var/ (IndexedDB) to keep it.
Cryo Studio opens .cryo files.
Cryo\Engine
$e = Cryo\Engine::current();
$e->redefineFunction('score_bonus', fn (int $n) => $n * 3); // the function body changes in place
$e->journal(); $e->revert($id); $e->exportJournal();
Hot patch and console from the IDE (JumPHP\Cryo\HotPatch)
The JumPHP IDE's Cryo window, tab Hot patch & console, on a program run with Run with memory metrics
(JUMPHP_CRYO_METRICS; the requests are files in var/cryo/hotpatch/, answered between two frames):
- Patch the method at the cursor: the method (or function) under the editor's cursor, as it is in the editor now, replaces the
running one (
redefineMethod): the level, the player, the connections stay. A constant can be set too. Every change is in the journal and can be undone one by one or all (revert). - Console: PHP typed into the running game (
$engine,$scene= the scene on top; variables kept from one line to the next; the last expression's value is shown), with Monaco's PHP colours and completions read from the program itself ($scene->, the real object's methods and properties;Class::;$; functions and classes). Enter runs, Shift+Enter a new line, ↑ ↓ the history. - Claude:
cryo_patch(path + line),cryo_patch_constant,cryo_patch_revert,cryo_console(the IDE's MCP server).
Desktop only (the browser has no ext-cryo); the code of the file is not changed by a patch: save the fix as usual.
Metrics
cryo_metrics() (memory, live objects, calls), cryo_metrics_sample() / cryo_metrics_mark() (.cryom series). The
browser has no HTTP server: the Prometheus text and the events reach the page as cryo events:
addEventListener('cryo', (e) => console.log(e.detail.kind, e.detail.text)); // kind 1 = metrics JSON
The sandbox in the browser (asynchronous)
In the browser a Cryo\Sandbox\Sandbox is a Web Worker that starts its own PHP instance (the same engine and the
same files as the game, engine/web/jumphp-cryo-worker.js): its memory is separate, and an exit(), a fatal error,
going over memory_limit or a WebAssembly trap never touch the game. On the desktop it is a child PHP process; the
same code works on both.
The browser calls PHP frame by frame (no JSPI, no Asyncify, no SharedArrayBuffer): nothing can wait. So only the
asynchronous API exists in the browser; call(), eval(), get(), set(), include(), metrics(), proxy(),
Future::await() on a future not ready yet, awaitAll/awaitAny, Pool::call/map, recv() throw a
SandboxException: "synchronous calls are not possible in the browser: use callAsync()->then() or Sandbox::wait()".
Send (returns a Cryo\Sandbox\Future) |
|
|---|---|
callAsync('fn', [args]), callAsync(['Class', 'method'], [args]) |
a call |
evalAsync('return 1 + 1;'), includeAsync('src/x.php') |
code |
getAsync('name'), setAsync('name', $value) |
global variables of the sandbox |
metricsAsync() |
memory, calls, live objects of the sandbox |
send($message) / messages() |
messages (Cryo\Sandbox\Channel::parent()->send() on the sandbox side) |
Read a Future (never blocking) |
|
|---|---|
status() |
'pending', 'ready', 'failed', 'cancelled' |
isReady(), isFailed(), isCancelled() |
the same flags as booleans |
value() |
the value once ready, else null |
error() |
the exception once failed: RemoteException (exception in the sandbox, getRemoteClass()), SandboxMemoryException, SandboxTimeoutException, SandboxCrashedException (getExitCode(), getStderr()), SandboxException |
then(fn ($v) => ..., fn (\Throwable $e) => ...) |
a new future; the callbacks run between two frames |
cancel() |
a request not started yet is never run |
Sandbox::wait($future or [$futures], ?$timeout) |
a future settled once all are (values, same keys) |
Sandbox::pump(), Sandbox::pending() |
reads what arrived and runs the callbacks; number still waiting |
The loop: JumPHP\Cryo\SandboxLoop
SandboxLoop::spawn($options) creates the sandbox and adds to the game's ReactPHP loop (GameLoop, the one that turns
once per frame in the browser) a periodic timer that calls Sandbox::pump(): answers arrive and then() callbacks run
between two frames, without ever waiting. SandboxLoop::wait() returns a JumPHP\Async\Task (same API as tasks:
then(), isDone(), result()).
use JumPHP\Cryo\SandboxLoop;
final class PuzzleScene extends AbstractScene
{
private ?\Cryo\Sandbox\Sandbox $sb = null;
private string $text = '';
public function enter(array $params = []): void
{
// in enter(): the sandbox's PHP boots in its Worker (~0.5-1 s), requests wait for it over there
$this->sb = SandboxLoop::spawn([
'timeout' => 2, // per request: above it the Worker is terminated -> SandboxTimeoutException
'memory_limit' => '64M', // over it -> SandboxMemoryException
'disable_functions' => ['exec'],
'bootstrap' => 'src/Puzzle/rules.php',
'restart' => 'on_crash', // a new instance after a crash
]);
$this->sb->callAsync('solve', [$this->grid])
->then(fn ($moves) => $this->text = count($moves) . ' moves',
fn (\Throwable $e) => $this->text = $e->getMessage());
SandboxLoop::wait([$this->sb->evalAsync('return 6 * 7;'), $this->sb->getAsync('version')], 5.0)
->then(fn (array $v) => ..., fn (\Throwable $e) => ...);
}
public function exit(): void
{
$this->sb?->kill();
}
public function render(Renderer $r): void
{
// the flags, read at every frame without waiting: $future->status() === 'pending' ...
}
}
- A sandbox runs its requests one at a time: a slow request (or an endless loop, until its
timeout) delays the next ones of the same sandbox. Two sandboxes work in parallel. timeout(seconds, per request): the page terminates the Worker (worker.terminate()) and the future fails withSandboxTimeoutException; the next requests of that sandbox fail (SandboxCrashedException, code 124) and, withrestart => 'on_crash', the next request starts a new instance.- Fatal error,
memory_limit,exit(): the sandbox answers first (SandboxMemoryException,SandboxException), then its instance ends. - A trap (engine stack overflow...) or a Worker error:
SandboxCrashedException(code 134,getStderr(): the Worker's message). start => 'fork'does not exist in the browser (no copy of an instance):spawn(default) orsnapshot.- Values travel serialized (
serialize): numbers, strings, arrays, plain objects; no closures nor resources. 32-bit integers in the browser (§2 of AGENTS.md).
Demo: games/cryo-sandbox-demo (bin/jumphp build cryo-sandbox-demo, bin/jumphp webshot cryo-sandbox-demo 8),
played at https://jumphp.net/cryo-sandbox-demo/jouer.
The JavaScript side
engine/web/jumphp.js installs Module.cryoHost (EM_JS functions of ext-cryo/cryo_host.c) with the host of
engine/web/jumphp-cryo.js:
Module.cryoHost. |
|
|---|---|
spawn(json) → id |
starts a jumphp-cryo-worker.js Worker ({"timeout": s, "memory_limit": bytes}) |
send(id, bytes) |
bytes to the sandbox; each complete frame (12-byte header + payload) goes in one postMessage |
recv(id, cap) |
at most cap bytes already arrived; null: nothing yet; -2: the sandbox has ended |
kill(id), status(id), error(id) |
status: -1 while it runs, else its exit code (124 timeout, 134 trap, 137 killed) |
In the Worker, each frame received is put into its PHP's cryoHost.recv, then Module._cryo_sandbox_step() (exported
by the engine) runs one request and sends its answers back through cryoHost.send(0, ...). When a request starts,
cryoHost.arm(ms, frame) gives the page the prepared "timeout" answer: that is what PHP receives if the page has to
terminate the Worker. window.JumPHP.cryoSandboxes lists the instances (debugging).
In the JumPHP IDE, the Cryo window shows all this without code: live memory of a run, snapshots taken and compared, freeze files, series, and a sandbox console (ide.md).
Whole-program save points (desktop, the IDE's Cryo window): JumPHP\Cryo\ProcessFreeze freezes the running game with
cryo_freeze($file, ['include' => ['globals', 'statics'], 'on_resource' => 'descriptor', 'key' => ...]) between two
frames, and a new process started with JUMPHP_CRYO_THAW thaws it before booting (Application::boot() returns the
thawed application): cryo_register_resource('SDL Renderer' / 'SDL Texture') and cryo_on_thaw +
CryoThawContext::replaceClass() make the native parts again (window, renderer, textures from Sdl::$recipes, fonts,
sounds, gamepads). Files are signed with a key of the project (var/cryo/savepoints/.key).