lardon3d/docs/development/concurrency.md

# Règles de concurrence

## Vue d'ensemble

Lardon3D utilise un modèle de concurrence à thread unique pour ncurses
et un modèle multi-thread pour le traitement. La séparation est stricte :
le thread ncurses ne fait jamais de travail métier, et les workers ne
touchent jamais ncurses.

## Modèle de concurrence

```text
Thread principal (ncurses)
├── Gestion des entrées
├── Affichage TUI
└── Orchestration

Worker thread
├── Exécution des tâches
├── Calculs métier
└── Écritures de résultats

SSD operation thread (0 ou 1, joinable)
└── Un poll ou contrôle UDisks synchrone borné, sans ncurses ni Task
```

## Règles fondamentales

### 1. ncurses appartient au thread principal

```c
// ✅ Correct : appel depuis le thread principal
mvprintw(0, 0, "Progression: %d%%", progress);

// ❌ Interdit : appel depuis un worker
// mvprintw() dans un thread secondaire
```

### 2. Variables partagées protégées par mutex

```c
// ✅ Correct
pthread_mutex_lock(&queue->mutex);
queue->count++;
pthread_mutex_unlock(&queue->mutex);

// ❌ Interdit
// queue->count++; sans protection
```

### 3. Variables de condition pour la synchronisation

```c
// Producteur (caller de la Task Queue)
pthread_mutex_lock(&queue->mutex);
queue->ready = true;
pthread_cond_signal(&queue->cond);
pthread_mutex_unlock(&queue->mutex);

// Consommateur (worker)
pthread_mutex_lock(&queue->mutex);
while (!queue->ready) {
    pthread_cond_wait(&queue->cond, &queue->mutex);
}
// traitement
pthread_mutex_unlock(&queue->mutex);
```

### 4. Pas de callback ncurses depuis un worker

```c
// ✅ Correct : le worker signale au thread principal
void worker_callback(task_t *task, void *userdata) {
    shared_state_t *state = userdata;
    pthread_mutex_lock(&state->mutex);
    state->result_ready = true;
    pthread_cond_signal(&state->cond);
    pthread_mutex_unlock(&state->mutex);
}

// ❌ Interdit : appel ncurses depuis le worker
// void worker_callback(...) {
//     mvprintw(...);
// }
```

## Primitives utilisées

| Primitive | Usage |
|---|---|
| `pthread_mutex_t` | Protection des données partagées |
| `pthread_cond_t` | Synchronisation producteur/consommateur |
| `pthread_create()` | Création des workers |
| `pthread_join()` | Attente de fin des workers |
| `pthread_cancel()` | Non utilisé pour interrompre une Task ; annulation coopérative |

## Invariants de concurrence

1. **Un seul thread ncurses** : ncurses n'est jamais appelé depuis un
   worker. Toute mise à jour de l'UI passe par des variables partagées
   protégées.

2. **Mutex hiérarchique** : si plusieurs mutex sont acquis, toujours dans
   le même ordre pour éviter les deadlocks.

3. **Annulation coopérative** : les workers vérifient périodiquement un
   drapeau d'annulation. Une Task n'est pas interrompue brutalement.

4. **Réservation atomique** : la réservation du gouverneur est atomique.
   Deux threads ne peuvent pas obtenir la même réservation.

5. **Pas de callback sans réservation** : aucun callback de tâche n'est
   invoqué sans réservation active. Cet invariant est maintenu même en
   présence d'erreurs.

6. **Retraite après callback** : la notification terminale finit avant la
   destruction du userdata. Queue détruit la Task hors de son mutex et ne
   conserve ensuite qu'un snapshot borné.

7. **Fermeture d'ingress** : le propriétaire empêche les nouveaux appels Queue
   avant `destroy()`. La fermeture interne attend le worker et chaque appel
   enregistré avant le close ; elle ne peut rendre sûr un appel démarré après
   la libération d'un pointeur C brut.

8. **Parallélisme scientifique propriétaire** : lorsqu'un kind emploie des
   participants internes, le callback Queue demeure l'unique propriétaire. Le
   nombre de participants et leur mémoire sont admis par le Governor ; seul le
   propriétaire publie le préfixe durable ordonné et joint tous les enfants.

9. **Lease SSD par objet** : un lease scratch appartient à l'adresse exacte de
   l'objet fourni par le caller. Tous ses champs sont lus/écrits sous le mutex
   du contrôleur. Le caller lui garantit un accès exclusif et ne le copie, ne le
    déplace ni ne le présente simultanément à deux contrôleurs. En production,
    acquire/release passent par les wrappers Governor ; le Governor relâche son
    mutex avant l'appel contrôleur, et le contrôleur ne rappelle jamais le
    Governor. À la saturation légale `generation == UINT64_MAX`, seule la fin
    du wrapper exact déjà sérialisé peut réconcilier sa propre opération et le
    compte fondé sur les adresses ; une update publique au même watermark ne
    peut pas rendre une autorité stale.

10. **Owner SSD unique** : la TUI/main demande et poll l'opération ; au plus un
    thread joinable exécute une opération bornée et ne touche jamais ncurses.
    Le destroy le joint avant unregister. Une observation malformée enregistre
    `ERROR` et ne confère aucune autorité de contrôle ou de lease.

11. **Frontière projet** : les vues libèrent leurs borrows, puis la Queue est
    annulée/jointe/détruite avant Project DB. Une Queue vide est créée ensuite.
    Aucun callback terminal ne peut donc déréférencer une DB déjà fermée et
    l'histoire d'un projet ne fuit pas dans le suivant.

12. **Ordre d'arrêt global** : Queue et leases Task, puis fermeture projet,
    join/unregister du binding SSD, contrôleur SSD, et enfin Governor. Un
    unregister encore bloqué par un lease est un échec observable, jamais un
    pointeur abandonné.

## Anti-patterns

### Deadlock

```c
// ❌ Risque de deadlock
pthread_mutex_lock(&mutex_a);
pthread_mutex_lock(&mutex_b);  // attend mutex_b

// Dans un autre thread :
pthread_mutex_lock(&mutex_b);
pthread_mutex_lock(&mutex_a);  // attend mutex_a → DEADLOCK
```

**Solution** : toujours acquérir les mutex dans le même ordre.

### Race condition

```c
// ❌ Race condition
if (task->state == TASK_STATE_QUEUED) {
    task->state = TASK_STATE_RUNNING;
}

// ✅ Correct
pthread_mutex_lock(&task->mutex);
if (task->state == TASK_STATE_QUEUED) {
    task->state = TASK_STATE_RUNNING;
}
pthread_mutex_unlock(&task->mutex);
```

### Use-after-free

```c
// ❌ Use-after-free
task_destroy(task);
task_callback(task);  // task est libéré

// ✅ Correct : le callback est entièrement revenu avant la destruction
task_callback(task);
task_destroy(task);
```

## Validation

Les readers Visual Index sont sans état partagé mutable. Une query copie la
liste bornée des segments sous le mutex DB, puis effectue hash, lectures et
accumulation après déverrouillage. Un update ne rend le nouveau segment visible
qu'au commit memberships+segment ; une query en cours garde son snapshot.

Pour tout ticket touchant la concurrence, exécuter :

```sh
# Build TSan
CC=clang meson setup build-tsan --wipe -Db_sanitize=thread -Db_lundef=false
meson compile -C build-tsan -j8
meson test -C build-tsan --print-errorlogs
```

TSan détecte automatiquement :

- les accès concurrents conflictuels instrumentés ;
- certaines utilisations incohérentes des primitives de synchronisation.

Il ne prouve pas l'absence de deadlock, de signal perdu ou de bug dans une
bibliothèque non instrumentée. Les invariants de lifetime et d'ordre de locks
restent donc soumis aux tests déterministes et à la revue.

### Preuve TSan globale courante

La matrice fraîche emploie GCC/G++ 16.2.1 et désactive explicitement Vulkan.
Elle passe 14/14 cibles couvrant Task, Project, Queue, Governor, registre/leases
SSD, contrôleur SSD, observateur/TUI async, Candidate, Visual Index, Feature,
Matcher et GV, puis 220/220 répétitions déterministes : **234/234** au total.

La seule liste de suppressions est `tests/tsan-opencv.supp`, limitée aux objets
partagés externes non instrumentés `libopencv_features.so`,
`libopencv_core.so` et `libtbb.so`. Elle ne masque aucune frame Lardon3D. Les
warnings GCC `-Wmaybe-uninitialized` des contrôles OpenCV Feature/SIFT sont
classés non matériels : le callback fournit une Task non nulle et le helper
initialise la structure avant toute autre sortie d'échec. Les warnings OpenCV
du build GV appartiennent aux headers externes.

Cette preuve TSan ne vaut pas validation de concurrence Vulkan. Le backend
ORB Vulkan réel est couvert séparément par le build Clang Vulkan-on 939/939,
la suite 65/65 et ses tests de backend/handle/publication ; cette séparation
doit rester explicite dans tout rapport.

## Checklist de concurrence

Avant de livrer un ticket touchant la concurrence :

- [ ] Toutes les variables partagées sont protégées par un mutex
- [ ] Les mutex sont toujours libérés (même en cas d'erreur)
- [ ] Les variables de condition sont vérifiées dans une boucle `while`
- [ ] Aucun appel ncurses depuis un worker
- [ ] L'annulation des Tasks est coopérative (pas de `pthread_cancel`)
- [ ] TSan ne signale aucune erreur
- [ ] Le build ASan ne signale aucune fuite mémoire liée aux threads