EN

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.php to 13_securite.php).
  • docs/cryo.md in 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-demo of JumPHP.