# 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](https://jumphp.net/cryo-sandbox-demo/jouer). Analysis application:
[Cryo Studio](https://jumphp.net/cryo-studio).

## 1. What fills the memory?

A picture of the PHP heap, then the classes that weigh the most:

```php
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

```php
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:

```php
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()`:

```php
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

```php
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

```php
$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)

```php
$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

```php
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:

```php
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

```php
$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](https://git.jumphp.net/jumphp/php-cryo/src/branch/main/docs/guide/README.md) (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](https://git.jumphp.net/jumphp/php-cryo/src/branch/main/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](https://jumphp.net/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](https://jumphp.net/cryo-sandbox-demo): its code is in `games/cryo-sandbox-demo` of JumPHP.
