lardon3d/docs/architecture/task_queue.md

# File de tâches (Task Queue)

## Objectif et responsabilités

Le module `task_queue` implémente la file d'attente FIFO des tâches de
traitement. Il orchestre l'exécution séquentielle des tâches via un worker
unique, gère la sélection de la prochaine tâche admissible et transmet les
callbacks de résultat.

La file est le point central entre les producteurs et le worker d'exécution.
Les responsabilités historiques de scheduler sont portées par cette Queue et
le runtime existants : aucun second scheduler n'existe. La Queue ne décide
jamais des ressources ; elle demande l'admission au Governor.

## Fichiers

- `include/lardon3d/task_queue.h` — types publics et API
- `src/task_queue.c` — implémentation
- `tests/test_task_queue.c` — tests unitaires

## Types principaux

Le type public réel est l'opaque `Lardon3DTaskQueue`.

## API publique

| Fonction | Description |
|---|---|
| `lardon3d_task_queue_create()` | Crée une file bornée et son worker |
| `lardon3d_task_queue_destroy()` | Arrête, annule, attend puis libère la file |
| `lardon3d_task_queue_add()` | Ajoute avec backpressure bloquante |
| `lardon3d_task_queue_try_add()` | Ajoute sans bloquer si une place existe |
| `lardon3d_task_queue_try_add_ex()` | Distingue succès, saturation, arrêt, collision d'ID et erreur |
| `lardon3d_task_queue_pause()` / `resume()` | Contrôle une tâche par son ID stable |
| `lardon3d_task_queue_cancel()` | Demande l'annulation par ID |
| `lardon3d_task_queue_remove()` | Retire un snapshot terminal retenu |
| `lardon3d_task_queue_snapshot()` | Copie une vue bornée de la file |
| `lardon3d_task_queue_observe()` | Copie la vue additive typée/durable/admission |

## Comportement FIFO avec bypass stable des WAIT

1. `lardon3d_task_queue_add()` ajoute la tâche en fin de file.
2. Le sélecteur interne parcourt la file du début vers la fin.
3. La première tâche `PENDING` admissible (non terminale) est
   retournée.
4. Si aucune tâche n'est admissible, le worker attend un changement.
5. L'ordre de soumission est respecté entre tâches admissibles ; une tâche en
   `WAIT` ressources peut être dépassée sans être réordonnée ou supprimée.

Lorsqu'au moins une tâche PENDING reste en `WAIT` de ressources, cette attente
est temporisée à 500 ms maximum. À l'expiration, le worker reprend le scan stable
depuis la tête et le chemin d'admission capture de nouveaux snapshots. Enqueue,
resume, `resources_changed`, annulation et arrêt continuent de réveiller
immédiatement le worker ; le timeout n'impose donc jamais 500 ms après un signal.
Cette règle utilise le worker unique existant et n'ajoute aucun thread.

## Sélection adaptative

Le sélecteur saute les tâches pour lesquelles le governor répond `WAIT` et
retourne la première tâche réellement admissible. Cela évite
le blocage par la tête de file lorsqu'une tâche ne peut pas démarrer.

## Invariants

1. **Worker unique** : une seule tâche s'exécute à la fois. Pas de parallélisme
   interne à la file.
2. **FIFO stable** : le scan commence à la tête et ne contourne que les
   `WAIT` d'admission. Il n'existe ni priorité cachée ni réordonnancement.
3. **Réservation obligatoire** : aucune tâche n'est exécutée sans réservation
   validée par le gouverneur.
4. **Notification terminale unique** : le callback terminé de la Task retourne
   avant la destruction de son userdata. Les callbacks métier peuvent avoir
   plusieurs séquences admises.
5. **Annulation sûre** : annuler une tâche en cours la met en état
   `CANCELLED` sans interrompre brutalement le worker.
6. **Retraite prompte et bornée** : après retour du callback terminé, la vraie
   Task est détruite hors mutex et seule une copie de snapshot demeure. Les 64
   terminaisons les plus récentes sont retenues ; les plus anciennes sont
   évincées sans conserver userdata ni Task.
7. **Fermeture coordonnée** : `destroy()` ferme d'abord l'ingress, attend le
   worker et tout appel enregistré avant la fermeture, puis libère mutex et
   mémoire exactement une fois. Le propriétaire doit interdire tout nouvel
   appel API dès que la destruction commence.
8. **IDs non réutilisés** : la génération est monotone. Après consommation ou
   génération de `UINT64_MAX`, l'épuisement est permanent pour la vie de la
   Queue ; un ID restauré plus petit ou une éviction d'historique ne la réarme
   jamais.
9. **Observation complète bornée** : la Queue de production accepte au plus 64
   pending, possède au plus une active et retient 64 terminaux. Une capacité
   additive de 129 observe donc tout l'état courant. Les Tasks vivantes sont
   copiées d'abord en ordre de soumission décroissant, puis l'histoire en ordre
   de terminaison décroissant ; l'actif ne peut pas être caché par l'histoire.

## Interactions

- **task** : chaque entrée de la file est un `Lardon3DTask` avec son état et sa
  progression.
- **runtime / producteurs** : soumettent les Tasks ; la Queue applique FIFO et
  orchestre l'exécution via le worker.
- **resource_governor** : la file consulte directement le gouverneur avant
  d'exécuter chaque tâche.
- **hardware_profile / resource_snapshot** : informations matériel utilisées
  par le gouverneur pour les réservations.

## Statut

**GATE G — PASS / FROZEN** — file FIFO stable avec worker unique,
sélection adaptative, réévaluation autonome des `WAIT`, pause, annulation
coopérative et accueil des tâches restaurées avec ID préassigné.

La reprise projet utilise `try_add_ex()` et ne bloque jamais `project_open()`.
À saturation, elle arrête sa fenêtre : les tâches non transférées restent
`PENDING` en DB et seront réévaluées lors d'une ouverture ultérieure. Ce n'est
pas un second scheduler.

Ouvrir, fermer ou changer de projet détruit/joint cette Queue avant fermeture
de Project DB, puis recrée une unique Queue vide. L'histoire et son namespace
d'IDs ne traversent donc jamais une frontière projet ; ce reset ne modifie pas
les Task IDs durables conservés dans chaque DB.

Les callbacks terminés sont appelés sans le mutex Queue. Tant que le
propriétaire maintient la Queue vivante, ils peuvent employer les lectures
`get`, `get_at`, `count` et `snapshot`. Ils ne doivent pas appeler
synchroniquement `remove()` sur leur propre record, `destroy()` sur la même
Queue, ni une opération dont l'achèvement dépend de leur propre retour.

## Limites

- Worker unique : pas de parallélisme inter-Tasks. Un kind peut posséder un
  parallélisme interne borné et chargé dans sa réservation.
- Pas de DAG ni de dépendances inter-tâches.
- Pas de priorités (FIFO stable avec bypass des seuls `WAIT`).
- La reprise ne possède pas encore de DAG ni de déclenchement différé lorsque
  une place se libère pendant la session courante.
- Pas de pool de workers CPU/IO/GPU.
- La backpressure borne les producteurs à la capacité configurée.
- Les 500 ms concernent uniquement l'admission initiale PENDING. Le polling
  existant à une rupture de séquence reste 50 ms.