Apps, CLI apps, graphic apps and IDE plugins are made in apps/<id>; bin/jumphp, the tools, the workflows, the IDE and the docs find a project in games/ or apps/. New projects get config/project.yaml (under project:); the engine, bin/jumphp, the tools and the IDE still read config/game.yaml (under game:). JUMPHP_APP is read before JUMPHP_GAME. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01X3cUrphmz1MoDiCrUbAHuo
9.2 KiB
Threads et TrueAsync
JumPHP sait faire tourner du travail lourd dans de vrais threads grâce à TrueAsync : génération de niveaux, recherche de chemin, IA, images procédurales… La frame n'attend jamais, le jeu reste à 60 images par seconde.
Exemple complet : games/hello-threads, une fractale calculée par un pool de
threads.
Deux runtimes
default |
async |
|
|---|---|---|
| PHP | 8.3 NTS (php:8.3-cli-bookworm) |
8.6 ZTS, fork TrueAsync (php-8.6.0-trueasync-0.11.3 + ext/async v0.11.3) |
| Image | jumphp/desktop:dev (docker/desktop) |
jumphp/desktop-async:dev (docker/desktop-async, ~15 min la première fois) |
| Extensions | SDL2, SDL_image, SDL_mixer, SDL_ttf, GD… | les mêmes, mêmes commits, + true_async et libuv 1.52.1 |
JumPHP\Async |
sans threads : travail réparti entre les frames | vrais threads (pool, un thread par tâche) |
| Navigateur | moteur WebAssembly PHP 8.5 ; JumPHP\Async passe par des Web Workers (voir plus bas) |
idem |
Un jeu choisit son runtime dans config/project.yaml :
project:
runtime: async
bin/jumphp run|test|shot|install|export:desktop prennent alors l'image async (construite automatiquement
au premier usage, ou bin/jumphp setup async). JUMPHP_RUNTIME=default|async force l'un ou l'autre, par
exemple pour vérifier qu'un jeu async marche aussi sans threads :
JUMPHP_RUNTIME=default bin/jumphp test hello-threads
JUMPHP_RUNTIME=async bin/jumphp test engine # tests du moteur avec de vrais threads
Tout le moteur (et Pong, le casse-briques…) tourne tel quel sur le runtime async.
L'API : JumPHP\Async
$tasks = $this->engine->tasks();
// une tâche, un thread
$task = $tasks->thread(static fn () => Maze::generate(64, 48, $seed));
// un pool : N threads démarrés une fois, beaucoup de petits travaux
$pool = $tasks->pool(); // un worker par cœur (Tasks::workers())
$pool->submit(static fn (int $y) => Fractal::row($y, 192), $y)
->then(fn (string $row) => $this->rows[$y] = $row, // appelé sur le thread principal
fn (\Throwable $e) => ...);
$task->isDone(); $task->isOk(); $task->result(); $task->error();
$pool->close(); // dans exit()
- Le moteur interroge les tâches au début de chaque frame, avant
update()des scènes : les callbacks dethen()s'exécutent là, sur le thread principal, et peuvent donc modifier la scène. submit()ne bloque jamais : la file de TrueAsync est gardée courte (64 travaux), le reste attend dans une réserve locale vidée à chaque frame. AvecAsync\ThreadPool::submit()brut, une file pleine suspend l'appelant, c'est-à-dire qu'elle gèle le jeu.Tasks::backend()dit où le travail tourne :'threads'(TrueAsync),'workers'(navigateur) ou'frames'(runtimedefault: thread principal, entre les frames,$tasks->budgetms par frame, 4 par défaut, au moins un travail).Tasks::threaded()est vrai pour les deux premiers.
Ce qui passe dans un thread
Un thread est un autre monde PHP : il reçoit une copie de la closure et de ses arguments. Le moteur y
charge l'autoloader du jeu (vendor/autoload.php) ; il n'y a ni moteur, ni SDL, ni scène, ni conteneur.
static fnobligatoire : une closure écrite dans une méthode emporte$this(la scène, avec ses ressources SDL) même si elle ne s'en sert pas. JumPHP la refuse avec uneLogicException, dans les deux modes, pour que l'erreur se voie aussi sans threads.- Des valeurs simples à l'aller et au retour : entiers, flottants, chaînes, tableaux, objets simples. Pas de
références (
&$x), pas de ressources (fichiers, textures, sons), pas d'objets à propriétés dynamiques. - Le code des threads va dans des classes statiques à part (
src/Work/dans hello-threads, exclu du conteneur dansconfig/services.yaml). - Une exception dans un thread revient en
JumPHP\Async\TaskFailed(classe, message, fichier et ligne d'origine). Une exception non rattrapée dans un thread brut TrueAsync serait relancée dans le thread principal, au milieu d'unusleep(): JumPHP enveloppe chaque travail pour l'éviter.
Quand les résultats arrivent
TrueAsync signale la fin d'un thread par son reactor (libuv), qui ne tourne que lorsque le thread principal
attend : usleep(), Async\delay(1)… mais pas Async\suspend() ni Async\delay(0).
- Sur le bureau, la boucle ReactPHP dort entre deux frames : les résultats arrivent naturellement.
- En headless (
test,shot), les frames s'enchaînent sans pause :Tasks::poll()attend alors 1 ms par frame, et seulement tant que des tâches sont en cours. - Il ne faut jamais boucler sur
isDone()sans rendre la main.
Mesures (i7-8565U, 4 cœurs, hello-threads, boucle temps réel)
| Image 192×144, 2500 itérations | thread principal (4 ms/frame) | pool de 4 threads |
|---|---|---|
| temps de calcul | 1,3 à 2,8 s | 0,24 à 0,76 s |
| images / seconde du jeu | 60 | 60 |
Calcul brut : 4 parts de travail en 0,66 s contre 0,36 s pour une seule, soit environ ×2,2 sur ce processeur portable (le turbo baisse quand les 4 cœurs travaillent).
Ce qu'il a fallu adapter (runtime async)
TrueAsync impose PHP 8.6 en ZTS. Les extensions SDL compilent sur 8.6 avec trois adaptations, toutes
dans docker/desktop-async et sans fork :
php86-compat.h, inclus de force (-include) :XtOffsetOf,WRONG_PARAM_COUNT,zval_dtor()etzend_exception_get_default()ont disparu de PHP 8.6 ; ils sont redéfinis avec leurs équivalents actuels (offsetof,zend_wrong_param_count(),zval_ptr_dtor_nogc(),zend_ce_exception).php-sdl/src/rect.c: lezend_unregister_functions()de MSHUTDOWN laisse une entrée invalide dans la table des fonctions sous 8.6 (segfault à la sortie de PHP). Il est retiré à la compilation (sed) : le moteur détruit ces fonctions lui-même.- libuv ≥ 1.45 est requis (Debian bookworm fournit 1.44) : il est compilé depuis les sources.
Ces correctifs pourraient être reportés dans les forks php-sdl (pour qu'ils compilent aussi en 8.6).
Dans le navigateur : un pool de Web Workers
Dans le navigateur, Tasks::backend() vaut 'workers'. La page (engine/web/jumphp.js) lance un pool de
Web Workers (engine/web/jumphp-worker.js), chacun avec son propre moteur PHP WebAssembly et les
fichiers du jeu. Le moteur n'est ni recompilé ni passé en ZTS, et il ne faut pas de SharedArrayBuffer : les
en-têtes COOP/COEP sont donc inutiles, et le jeu reste intégrable en iframe dans le portail.
jeu (PHP, thread principal) page (JS) worker n (PHP wasm)
Pool::submit(static fn ...)
-> /tmp/jumphp-tasks/out/<id>.job ─────────► worker libre ? postMessage ─► Worker::run()
(closure + arguments)
<- /tmp/jumphp-tasks/in/<id>.res ◄────────── écrit le résultat ◄────────── serialize([ok, valeur])
Tasks::poll() -> then()
- La closure voyage sous forme de code source et valeurs capturées, grâce à
laravel/serializable-closure (PHP pur, MIT). La même
static fnque pour les threads fonctionne. La classe où elle est écrite (pourself::) doit être chargeable par l'autoloader, ce qui est le cas des scènes. - Nombre de workers : nombre de cœurs moins un, au plus 4.
?workers=Ndans l'URL de la page change ce nombre ;?workers=0le désactive. - Les workers démarrent dès qu'un pool est créé, puisqu'il faut 0,5 à 1 s pour démarrer chaque moteur. Un
worker qui plante est relancé, et sa tâche échoue en
TaskFailed(WorkerError). Si aucun worker ne démarre (navigateur trop ancien, mémoire), la page le signale et PHP refait les tâches lui-même, entre les frames. - Chaque worker réserve sa propre mémoire WebAssembly (256 Mo au départ, allouée à la demande par le navigateur) : c'est pour cela que leur nombre est limité à 4.
- Le transport des fichiers se teste sans navigateur :
engine/tests/Async/WebWorkersTest.phpjoue le rôle de la page et des workers.
Mesure (Chrome sans écran, Docker, deuxième image de hello-threads) : 3 workers 4,55 s à 60 FPS, contre 7,55 s à 23 FPS sur le thread principal.
Pourquoi pas TrueAsync lui-même dans le navigateur
Les Web Workers suffisent pour la même API, mais TrueAsync compilé en WebAssembly buterait sur quatre points :
- Les coroutines. TrueAsync change de contexte avec les fibers Zend (assembleur boost ou
ucontext). Aucun des deux n'existe pour WebAssembly, et le fork n'a pas de code emscripten. Il faudrait un backend de fibers emscripten (emscripten_fiber_*), qui impose ASYNCIFY : binaire plus gros et PHP plus lent. JSPI (stack switching natif) pourrait remplacer ASYNCIFY plus tard. - libuv. C'est le reactor de TrueAsync, et il n'existe pas de portage WebAssembly maintenu.
- ZTS + pthreads. Il faudrait SharedArrayBuffer, donc les en-têtes COOP/COEP, ce qui gêne l'intégration en iframe.
- PHP 8.6. Le moteur WebAssembly devrait passer du 8.3 au fork 8.6.