NL

Cryo : mémoire, sandbox et code à chaud

Le moteur de JumPHP contient l'extension Cryo (depuis la version 0.5.57) : rien à installer, elle est là dans le navigateur comme sur le bureau. Elle sert à trois choses dans un jeu ou une application : comprendre la mémoire (qu'est-ce qui la remplit, qu'est-ce qui fuit, qui retient un objet), exécuter du code PHP isolé dans une sandbox qui ne peut ni planter ni geler le jeu, et changer le code à chaud sans recharger la page.

Démo jouable : Cryo Sandbox. Application d'analyse : Cryo Studio.

1. Qu'est-ce qui remplit la mémoire ?

Une photo du tas PHP, puis les classes qui pèsent le plus :

cryo_snapshot('/tmp/jeu.cryo');                     // le graphe de tous les objets, dans un fichier
$r = CryoReader::open('/tmp/jeu.cryo');
foreach ($r->top('class', 5) as $l) {
    echo "{$l['class']} : {$l['count']} objets, {$l['bytes']} octets\n";
}

top('retained') (le défaut) compte la taille retenue : ce qui serait libéré si ces objets disparaissaient. Le fichier va dans /tmp (perdu au rechargement) ou dans var/ (gardé dans le navigateur) ; Cryo Studio l'ouvre.

Exemple : une touche pour photographier

use JumPHP\Renderer\Renderer;
use JumPHP\Scene\AbstractScene;

final class NiveauScene extends AbstractScene
{
    private string $memoire = '';

    public function update(float $dt): void
    {
        if ($this->actions()->isPressed('debug')) {           // une action « debug » dans config/
            cryo_snapshot('/tmp/niveau.cryo');
            $top = CryoReader::open('/tmp/niveau.cryo')->top('class', 1)[0] ?? null;
            $this->memoire = $top ? "{$top['class']} x{$top['count']}" : 'vide';
        }
    }

    public function render(Renderer $r): void
    {
        $r->clear([0, 0, 0]);
        $this->font()->draw($r, strtoupper($this->memoire), 8, 8, 1, [255, 255, 0]);
    }
}

2. Qui garde cet objet en vie ?

Un ennemi mort qui ne disparaît pas de la mémoire, c'est presque toujours une liste qui le garde. Cryo donne le chemin, en direct, sans fichier :

foreach (cryo_roots_of($ennemi) as $chemin) {
    echo implode(' -> ', array_column($chemin, 'name')), "\n";    // ex. : Monde::$ecouteurs -> 12 -> cible
}

3. Trouver une fuite

Une fuite, ce sont des objets créés à la même ligne qui survivent et s'accumulent. Trois photos à des moments comparables (fin de chaque niveau, chaque minute…), puis delta() :

cryo_snapshot("/tmp/niveau-$n.cryo");               // à la fin de chaque niveau
// ... après le 3e :
foreach (CryoReader::delta(['/tmp/niveau-1.cryo', '/tmp/niveau-2.cryo', '/tmp/niveau-3.cryo']) as $l) {
    if ($l['growing']) {
        echo "fuite : {$l['site']}, gardés par {$l['hooked_by']}\n";
    }
}

site (la ligne du new) et hooked_by (la ligne qui les range quelque part) ne sont connus qu'avec le suivi des allocations (cryo.track_alloc=site : en ligne de commande, php -d cryo.track_alloc=site). Sans lui, delta() donne la même chose par classe : CryoReader::delta($photos, 'class').

4. Du code isolé : la sandbox

Une sandbox est une autre instance de PHP (dans le navigateur : un Web Worker ; sur le bureau : un processus). Une exception, une erreur fatale, un dépassement de mémoire ou une boucle infinie n'y touchent jamais le jeu. Pour des scripts écrits par les joueurs, des mods, une IA de jeu lente, un calcul lourd.

Dans le navigateur, PHP tourne image par image et ne peut pas attendre : tout est asynchrone. On envoie une requête, on reçoit un Future, et le jeu continue ; JumPHP\Cryo\SandboxLoop lit les réponses une fois par image par la boucle ReactPHP du moteur.

Exemple : le plus simple

use JumPHP\Cryo\SandboxLoop;

final class CalculScene extends AbstractScene
{
    private ?\Cryo\Sandbox\Sandbox $sb = null;
    private string $texte = 'calcul...';

    public function enter(array $params = []): void
    {
        $this->sb = SandboxLoop::spawn();
        $this->sb->callAsync('str_repeat', ['ab', 3])
            ->then(fn ($v) => $this->texte = $v);              // 'ababab', quelques images plus tard
    }

    public function exit(): void
    {
        $this->sb?->kill();
    }

    public function render(Renderer $r): void
    {
        $r->clear([0, 0, 40]);
        $this->font()->draw($r, strtoupper($this->texte), 8, 8, 2, [255, 255, 255]);
    }
}

Exemple : le code d'un joueur, avec des limites

$this->sb = SandboxLoop::spawn([
    'memory_limit' => '32M',                 // au-delà : SandboxMemoryException
    'timeout' => 1,                          // secondes par requête : au-delà, SandboxTimeoutException
    'disable_functions' => ['exec', 'system'],
    'restart' => 'on_crash',                 // une nouvelle instance après un plantage
]);

$this->sb->evalAsync($codeDuJoueur)->then(
    fn ($resultat) => $this->message = "résultat : " . var_export($resultat, true),
    fn (\Throwable $e) => $this->message = match (true) {
        $e instanceof \Cryo\Sandbox\RemoteException => "erreur : " . $e->getMessage(),
        $e instanceof \Cryo\Sandbox\SandboxTimeoutException => "trop long (boucle infinie ?)",
        $e instanceof \Cryo\Sandbox\SandboxMemoryException => "trop de mémoire",
        default => $e->getMessage(),
    },
);

Exemple : attendre plusieurs résultats (sans jamais dormir)

$a = $this->sb->callAsync('array_sum', [[1, 2, 3]]);
$b = $this->sb->evalAsync('return strtoupper("bonjour");');

SandboxLoop::wait(['somme' => $a, 'mot' => $b], 5.0)
    ->then(fn (array $v) => $this->texte = "{$v['somme']} {$v['mot']}",      // « 6 BONJOUR »
           fn (\Throwable $e) => $this->texte = $e->getMessage());

SandboxLoop::wait() renvoie une JumPHP\Async\Task : c'est la boucle d'événements qui attend, jamais un sleep.

Exemple : un drapeau lisible à chaque image

public function render(Renderer $r): void
{
    $couleur = match ($this->future->status()) {        // ne bloque jamais
        'pending' => [255, 200, 0],                     // en cours
        '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, $couleur);
}

Ce qu'on peut envoyer

Méthode (renvoie un Future)
callAsync('fonction', [arguments]), callAsync([Classe::class, 'methode'], [...]) un appel
evalAsync('return 1 + 1;'), includeAsync('src/regles.php') du code, un fichier du jeu
getAsync('nom'), setAsync('nom', $valeur) les variables globales de la sandbox
metricsAsync() sa mémoire, ses objets vivants

Les valeurs passent sérialisées : nombres, chaînes, tableaux, objets simples ; pas de closures ni de ressources. Les requêtes d'une même sandbox passent l'une après l'autre (deux sandboxes travaillent en parallèle). Le PHP d'une sandbox démarre en 0,5 à 1 s : créez-la dans enter(), les requêtes envoyées entre-temps attendent leur tour. Les appels synchrones (call(), eval(), await()) n'existent pas dans le navigateur : ils lèvent une exception qui le dit.

5. Changer le code à chaud

Cryo\Engine remplace une fonction ou une méthode pendant que le jeu tourne (essayer une règle, instrumenter le temps d'un diagnostic), et sait tout annuler :

use Cryo\Engine;

$e = Engine::current();
$id = $e->redefineFunction('degats', fn (int $force): int => $force * 3);     // le jeu utilise la nouvelle règle
$e->redefineMethod(Ennemi::class, 'vitesse', fn (): float => 0.5);           // $this disponible
$e->journal();                                                                // ce qui a changé
$e->revert($id);                                                              // annuler un changement
$e->revert();                                                                 // tout annuler

6. Mesurer

$m = cryo_metrics();                       // memory, memory_peak, objects_alive, gc_runs, gc_time...
cryo_metrics_class_counts(10);             // classe => nombre d'objets vivants
cryo_metrics_sample(100, 'var/partie.cryom');   // une courbe, un point toutes les 100 ms (Cryo Studio l'affiche)
cryo_metrics_mark('boss');                 // une marque dans la courbe

Pour aller plus loin

  • Le guide complet de l'extension : congeler un script et le reprendre ailleurs, redémarrer quand la mémoire monte, démarrage à chaud, fork, sandbox en ligne de commande, signature et chiffrement, cryo-inspect.
  • 13 exemples courts en ligne de commande, un par idée (01_snapshot.php à 13_securite.php).
  • docs/cryo.fr.md de JumPHP : le fonctionnement interne de la sandbox dans le navigateur (Workers, côté JavaScript, codes de sortie).
  • Cryo Studio : ouvrir les photos (.cryo) et les courbes (.cryom), fuites, dominateurs, requêtes, chemins, et un mode Live branché sur un programme qui tourne.
  • La démo Cryo Sandbox : son code est dans games/cryo-sandbox-demo de JumPHP.