155 lines
9 KiB
Markdown
155 lines
9 KiB
Markdown
# Cryo dans JumPHP
|
|
|
|
[ext-cryo](https://git.jumphp.net/jumphp/php-cryo) est liée en statique dans le moteur WebAssembly de JumPHP
|
|
(`docker/ext/cryo`, copiée depuis PhpCryo par `tools/sync-jumphp.sh`). Elle sert à quatre choses dans un jeu ou une
|
|
application : des **snapshots** du tas PHP (fuites de mémoire), leur **lecture** (`CryoReader`), la **réécriture à
|
|
chaud** du code (`Cryo\Engine`), des **métriques**, et des **sandboxes** : du code PHP isolé dans une autre instance
|
|
de PHP, qui ne peut ni planter ni geler le jeu.
|
|
|
|
Pour commencer, avec des exemples courts (une touche pour photographier la mémoire, trouver une fuite, le code d'un
|
|
joueur dans une sandbox, attendre plusieurs résultats, un drapeau lu à chaque image, changer une règle à chaud) :
|
|
**https://jumphp.net/docs/cryo**. Le guide complet de l'extension (congeler et reprendre un script, fork, métriques,
|
|
sécurité…) : [php-cryo, `docs/guide/`](https://git.jumphp.net/jumphp/php-cryo/src/branch/main/docs/guide/README.md),
|
|
et 13 exemples en ligne de commande : [`examples/`](https://git.jumphp.net/jumphp/php-cryo/src/branch/main/examples).
|
|
Cette page-ci décrit le fonctionnement en détail. English: [cryo.md](cryo.md).
|
|
|
|
## Snapshots et CryoReader
|
|
|
|
```php
|
|
cryo_snapshot(sys_get_temp_dir() . '/a.cryo', ['redact' => ['password']]); // le graphe d'objets, racines, orphelins
|
|
$r = CryoReader::open(sys_get_temp_dir() . '/a.cryo');
|
|
$r->top('class', 10); // qui prend la mémoire
|
|
$r->dominators(10); // qui RETIENT la mémoire
|
|
$r->path($id); // racine -> ... -> l'objet
|
|
cryo_roots_of($obj); // en direct, sans fichier : qui garde cet objet en vie ?
|
|
```
|
|
|
|
Dans le navigateur, le fichier est écrit dans le système de fichiers d'emscripten (`/tmp`), ou dans `var/`
|
|
(IndexedDB) pour le garder. [Cryo Studio](https://jumphp.net/cryo-studio) ouvre les `.cryo`.
|
|
|
|
## Cryo\Engine
|
|
|
|
```php
|
|
$e = Cryo\Engine::current();
|
|
$e->redefineFunction('score_bonus', fn (int $n) => $n * 3); // le corps de la fonction change en place
|
|
$e->journal(); $e->revert($id); $e->exportJournal();
|
|
```
|
|
|
|
## Métriques
|
|
|
|
`cryo_metrics()` (mémoire, objets vivants, appels), `cryo_metrics_sample()` / `cryo_metrics_mark()` (séries
|
|
`.cryom`). Dans le navigateur il n'y a pas de serveur HTTP : le texte Prometheus et les événements arrivent sur la
|
|
page en événements `cryo` :
|
|
|
|
```js
|
|
addEventListener('cryo', (e) => console.log(e.detail.kind, e.detail.text)); // kind 1 = JSON des métriques
|
|
```
|
|
|
|
## La sandbox dans le navigateur (asynchrone)
|
|
|
|
Un `Cryo\Sandbox\Sandbox` est, dans le navigateur, un **Web Worker qui démarre sa propre instance de PHP** (le même
|
|
moteur et les mêmes fichiers que le jeu, `engine/web/jumphp-cryo-worker.js`) : sa mémoire est séparée, un `exit()`,
|
|
une erreur fatale, un dépassement de `memory_limit` ou un *trap* WebAssembly n'y touchent jamais le jeu. Sur le
|
|
bureau, c'est un processus PHP fils ; le même code marche des deux côtés.
|
|
|
|
Le navigateur appelle PHP image par image (pas de JSPI, pas d'Asyncify, pas de SharedArrayBuffer) : **rien ne peut
|
|
attendre**. Seule l'API asynchrone existe donc dans le navigateur ; `call()`, `eval()`, `get()`, `set()`,
|
|
`include()`, `metrics()`, `proxy()`, `Future::await()` d'un futur pas encore prêt, `awaitAll/awaitAny`,
|
|
`Pool::call/map`, `recv()` lèvent une `SandboxException` :
|
|
« synchronous calls are not possible in the browser: use callAsync()->then() or Sandbox::wait() ».
|
|
|
|
| Envoyer (renvoie un `Cryo\Sandbox\Future`) | |
|
|
| --- | --- |
|
|
| `callAsync('fn', [args])`, `callAsync(['Class', 'method'], [args])` | appel |
|
|
| `evalAsync('return 1 + 1;')`, `includeAsync('src/x.php')` | code |
|
|
| `getAsync('nom')`, `setAsync('nom', $valeur)` | variables globales de la sandbox |
|
|
| `metricsAsync()` | mémoire, appels, objets vivants de la sandbox |
|
|
| `send($message)` / `messages()` | messages (`Cryo\Sandbox\Channel::parent()->send()` côté sandbox) |
|
|
|
|
| Lire un `Future` (jamais bloquant) | |
|
|
| --- | --- |
|
|
| `status()` | `'pending'`, `'ready'`, `'failed'`, `'cancelled'` |
|
|
| `isReady()`, `isFailed()`, `isCancelled()` | les mêmes drapeaux en booléens |
|
|
| `value()` | la valeur une fois prête, sinon `null` |
|
|
| `error()` | l'exception une fois en échec : `RemoteException` (exception dans la sandbox, `getRemoteClass()`), `SandboxMemoryException`, `SandboxTimeoutException`, `SandboxCrashedException` (`getExitCode()`, `getStderr()`), `SandboxException` |
|
|
| `then(fn ($v) => ..., fn (\Throwable $e) => ...)` | un nouveau futur ; les rappels tournent entre deux images |
|
|
| `cancel()` | une requête pas encore commencée n'est jamais exécutée |
|
|
| `Sandbox::wait($futur ou [$futurs], ?$timeout)` | un futur réglé quand tous le sont (valeurs, mêmes clés) |
|
|
| `Sandbox::pump()`, `Sandbox::pending()` | lit ce qui est arrivé et exécute les rappels ; nombre en attente |
|
|
|
|
### La boucle : `JumPHP\Cryo\SandboxLoop`
|
|
|
|
`SandboxLoop::spawn($options)` crée la sandbox et ajoute à la boucle ReactPHP du jeu (`GameLoop`, celle qui tourne
|
|
une fois par image dans le navigateur) un timer périodique qui appelle `Sandbox::pump()` : les réponses arrivent,
|
|
les rappels `then()` s'exécutent, entre deux images, sans jamais attendre. `SandboxLoop::wait()` renvoie une
|
|
`JumPHP\Async\Task` (même API que les tâches : `then()`, `isDone()`, `result()`).
|
|
|
|
```php
|
|
use JumPHP\Cryo\SandboxLoop;
|
|
|
|
final class PuzzleScene extends AbstractScene
|
|
{
|
|
private ?\Cryo\Sandbox\Sandbox $sb = null;
|
|
private string $text = '';
|
|
|
|
public function enter(array $params = []): void
|
|
{
|
|
// dans enter() : le PHP de la sandbox démarre dans son Worker (~0,5-1 s), les requêtes l'attendent là-bas
|
|
$this->sb = SandboxLoop::spawn([
|
|
'timeout' => 2, // par requête : au-delà, le Worker est terminé -> SandboxTimeoutException
|
|
'memory_limit' => '64M', // dépassé -> SandboxMemoryException
|
|
'disable_functions' => ['exec'],
|
|
'bootstrap' => 'src/Puzzle/rules.php',
|
|
'restart' => 'on_crash', // une nouvelle instance après un plantage
|
|
]);
|
|
$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
|
|
{
|
|
// les drapeaux, lus à chaque image sans attendre : $future->status() === 'pending' ...
|
|
}
|
|
}
|
|
```
|
|
|
|
- Une sandbox exécute ses requêtes **une par une** : une requête lente (ou une boucle infinie, jusqu'à son
|
|
`timeout`) retarde les suivantes de la même sandbox. Deux sandboxes travaillent en parallèle.
|
|
- `timeout` (secondes, par requête) : la page termine le Worker (`worker.terminate()`) et le futur échoue avec
|
|
`SandboxTimeoutException` ; les requêtes suivantes de cette sandbox échouent (`SandboxCrashedException`, code 124)
|
|
et, avec `restart => 'on_crash'`, la requête suivante démarre une nouvelle instance.
|
|
- Erreur fatale, `memory_limit`, `exit()` : la sandbox répond d'abord (`SandboxMemoryException`,
|
|
`SandboxException`), puis son instance se termine.
|
|
- Un *trap* (débordement de pile du moteur...) ou une erreur du Worker : `SandboxCrashedException` (code 134,
|
|
`getStderr()` : le message du Worker).
|
|
- `start => 'fork'` n'existe pas dans le navigateur (pas de copie d'instance) : `spawn` (par défaut) ou `snapshot`.
|
|
- Les valeurs passent sérialisées (`serialize`) : nombres, chaînes, tableaux, objets simples ; pas de closures ni de
|
|
ressources. Entiers 32 bits dans le navigateur (§2 de AGENTS.md).
|
|
|
|
Démo : `games/cryo-sandbox-demo` (`bin/jumphp build cryo-sandbox-demo`, `bin/jumphp webshot cryo-sandbox-demo 8`).
|
|
|
|
### Côté JavaScript
|
|
|
|
`engine/web/jumphp.js` installe `Module.cryoHost` (fonctions EM_JS de `ext-cryo/cryo_host.c`) avec l'hôte de
|
|
`engine/web/jumphp-cryo.js` :
|
|
|
|
| `Module.cryoHost.` | |
|
|
| --- | --- |
|
|
| `spawn(json)` → id | démarre un Worker `jumphp-cryo-worker.js` (`{"timeout": s, "memory_limit": octets}`) |
|
|
| `send(id, bytes)` | octets vers la sandbox ; chaque trame complète (en-tête 12 octets + charge) part en un `postMessage` |
|
|
| `recv(id, cap)` | au plus `cap` octets déjà arrivés ; `null` : rien encore ; `-2` : la sandbox est terminée |
|
|
| `kill(id)`, `status(id)`, `error(id)` | `status` : -1 tant qu'elle tourne, sinon son code de sortie (124 timeout, 134 trap, 137 tuée) |
|
|
|
|
Dans le Worker, chaque trame reçue est mise dans le `cryoHost.recv` de son PHP, puis
|
|
`Module._cryo_sandbox_step()` (exporté par le moteur) exécute **une** requête et renvoie ses réponses par
|
|
`cryoHost.send(0, ...)`. Au début d'une requête, `cryoHost.arm(ms, trame)` donne à la page la réponse « timeout »
|
|
préparée : c'est elle que PHP reçoit si la page doit terminer le Worker. `window.JumPHP.cryoSandboxes` liste les
|
|
instances (débogage).
|