Cryo: memory, sandbox and hot code
The JumPHP engine includes the Cryo extension (since version 0.5.57): nothing to install, it is there in the browser as on the desktop. It does three things for a game or an application: understand memory (what fills it, what leaks, what keeps an object alive), run isolated PHP code in a sandbox that can neither crash nor freeze the game, and change code while it runs without reloading the page.
Playable demo: Cryo Sandbox. Analysis application: Cryo Studio.
1. What fills the memory?
A picture of the PHP heap, then the classes that weigh the most:
cryo_snapshot('/tmp/game.cryo'); // the graph of every object, in a file
$r = CryoReader::open('/tmp/game.cryo');
foreach ($r->top('class', 5) as $l) {
echo "{$l['class']}: {$l['count']} objects, {$l['bytes']} bytes\n";
}
top('retained') (the default) counts the retained size: what would be freed if those objects went away. The
file goes to /tmp (lost on reload) or to var/ (kept in the browser); Cryo Studio opens it.
Example: a key to take a picture
use JumPHP\Renderer\Renderer;
use JumPHP\Scene\AbstractScene;
final class LevelScene extends AbstractScene
{
private string $memory = '';
public function update(float $dt): void
{
if ($this->actions()->isPressed('debug')) { // a "debug" action in config/
cryo_snapshot('/tmp/level.cryo');
$top = CryoReader::open('/tmp/level.cryo')->top('class', 1)[0] ?? null;
$this->memory = $top ? "{$top['class']} x{$top['count']}" : 'empty';
}
}
public function render(Renderer $r): void
{
$r->clear([0, 0, 0]);
$this->font()->draw($r, strtoupper($this->memory), 8, 8, 1, [255, 255, 0]);
}
}
2. What keeps this object alive?
A dead enemy that never leaves memory is nearly always held by some list. Cryo gives the path, live, without a file:
foreach (cryo_roots_of($enemy) as $path) {
echo implode(' -> ', array_column($path, 'name')), "\n"; // e.g. World::$listeners -> 12 -> target
}
3. Finding a leak
A leak is objects created at the same line that survive and pile up. Three pictures at comparable moments (end
of each level, every minute…), then delta():
cryo_snapshot("/tmp/level-$n.cryo"); // at the end of each level
// ... after the 3rd:
foreach (CryoReader::delta(['/tmp/level-1.cryo', '/tmp/level-2.cryo', '/tmp/level-3.cryo']) as $l) {
if ($l['growing']) {
echo "leak: {$l['site']}, kept by {$l['hooked_by']}\n";
}
}
site (the line of the new) and hooked_by (the line that stores them somewhere) are only known with allocation
tracking (cryo.track_alloc=site: on the command line, php -d cryo.track_alloc=site). Without it, delta() gives
the same per class: CryoReader::delta($pictures, 'class').
4. Isolated code: the sandbox
A sandbox is another PHP instance (in the browser: a Web Worker; on the desktop: a process). An exception, a fatal error, running out of memory or an endless loop never touch the game. For scripts written by players, mods, a slow game AI, a heavy computation.
In the browser PHP runs frame by frame and cannot wait: everything is asynchronous. You send a request, get a
Future, and the game goes on; JumPHP\Cryo\SandboxLoop reads the answers once per frame through the engine's
ReactPHP loop.
Example: the simplest
use JumPHP\Cryo\SandboxLoop;
final class ComputeScene extends AbstractScene
{
private ?\Cryo\Sandbox\Sandbox $sb = null;
private string $text = 'computing...';
public function enter(array $params = []): void
{
$this->sb = SandboxLoop::spawn();
$this->sb->callAsync('str_repeat', ['ab', 3])
->then(fn ($v) => $this->text = $v); // 'ababab', a few frames later
}
public function exit(): void
{
$this->sb?->kill();
}
public function render(Renderer $r): void
{
$r->clear([0, 0, 40]);
$this->font()->draw($r, strtoupper($this->text), 8, 8, 2, [255, 255, 255]);
}
}
Example: a player's code, with limits
$this->sb = SandboxLoop::spawn([
'memory_limit' => '32M', // above: SandboxMemoryException
'timeout' => 1, // seconds per request: above, SandboxTimeoutException
'disable_functions' => ['exec', 'system'],
'restart' => 'on_crash', // a new instance after a crash
]);
$this->sb->evalAsync($playerCode)->then(
fn ($result) => $this->message = "result: " . var_export($result, true),
fn (\Throwable $e) => $this->message = match (true) {
$e instanceof \Cryo\Sandbox\RemoteException => "error: " . $e->getMessage(),
$e instanceof \Cryo\Sandbox\SandboxTimeoutException => "too long (endless loop?)",
$e instanceof \Cryo\Sandbox\SandboxMemoryException => "too much memory",
default => $e->getMessage(),
},
);
Example: waiting for several results (never sleeping)
$a = $this->sb->callAsync('array_sum', [[1, 2, 3]]);
$b = $this->sb->evalAsync('return strtoupper("hello");');
SandboxLoop::wait(['sum' => $a, 'word' => $b], 5.0)
->then(fn (array $v) => $this->text = "{$v['sum']} {$v['word']}", // "6 HELLO"
fn (\Throwable $e) => $this->text = $e->getMessage());
SandboxLoop::wait() returns a JumPHP\Async\Task: the event loop does the waiting, never a sleep.
Example: a flag readable at every frame
public function render(Renderer $r): void
{
$colour = match ($this->future->status()) { // never blocks
'pending' => [255, 200, 0], // running
'ready' => [0, 220, 0], // $this->future->value()
'failed' => [255, 60, 60], // $this->future->error()
'cancelled' => [128, 128, 128], // $this->future->cancel()
};
$r->fillRect(8, 8, 10, 10, $colour);
}
What can be sent
Method (returns a Future) |
|
|---|---|
callAsync('function', [arguments]), callAsync([Klass::class, 'method'], [...]) |
a call |
evalAsync('return 1 + 1;'), includeAsync('src/rules.php') |
code, a file of the game |
getAsync('name'), setAsync('name', $value) |
the sandbox's global variables |
metricsAsync() |
its memory, its live objects |
Values travel serialized: numbers, strings, arrays, plain objects; no closures nor resources. The requests of one
sandbox run one after the other (two sandboxes work in parallel). A sandbox's PHP boots in 0.5 to 1 s: create it in
enter(), requests sent meanwhile wait their turn. Synchronous calls (call(), eval(), await()) do not exist in
the browser: they throw an exception that says so.
5. Changing code while it runs
Cryo\Engine replaces a function or a method while the game runs (trying a rule, instrumenting for a diagnosis),
and can undo everything:
use Cryo\Engine;
$e = Engine::current();
$id = $e->redefineFunction('damage', fn (int $strength): int => $strength * 3); // the game uses the new rule
$e->redefineMethod(Enemy::class, 'speed', fn (): float => 0.5); // $this available
$e->journal(); // what changed
$e->revert($id); // undo one change
$e->revert(); // undo everything
6. Measuring
$m = cryo_metrics(); // memory, memory_peak, objects_alive, gc_runs, gc_time...
cryo_metrics_class_counts(10); // class => live objects
cryo_metrics_sample(100, 'var/game.cryom'); // a curve, one point every 100 ms (Cryo Studio draws it)
cryo_metrics_mark('boss'); // a mark on the curve
Going further
- The complete guide of the extension (French): freezing a script and resuming it elsewhere, restarting when
memory grows, warm boot, fork, command-line sandbox, signing and encryption,
cryo-inspect. - 13 short command-line examples, one per idea (
01_snapshot.phpto13_securite.php). docs/cryo.mdin JumPHP: how the sandbox works inside the browser (Workers, the JavaScript side, exit codes).- Cryo Studio: open pictures (
.cryo) and curves (.cryom), leaks, dominators, queries, paths, and a Live mode plugged into a running program. - The Cryo Sandbox demo: its code is in
games/cryo-sandbox-demoof JumPHP.