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

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

// ✅ 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

// ✅ 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

// 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

// ✅ 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

// ❌ 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

// ❌ 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

// ❌ 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 :

# 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