Identifier et corriger la plus grosse fuite mémoire de Ghostty

• Une fuite grave a été découverte dans l’émulateur de terminal Ghostty, pouvant consommer plusieurs dizaines de Go de mémoire après une longue période d’exécution
• La cause du problème était liée à la logique non standard de réutilisation des pages mémoire de la structure PageList, où munmap n’était pas appelé, ce qui entraînait l’accumulation de mémoire non libérée
• Comme Claude Code CLI génère fréquemment des sorties graphiques à points de code multiples, l’utilisation de pages non standard a augmenté, rendant la fuite visible à grande échelle
• La correction a consisté à ne plus réutiliser les pages non standard et à les libérer immédiatement, avec suivi et validation de la fuite à l’aide de la fonction de tags VM de macOS
• Cette correction est considérée comme la résolution de la plus importante fuite de Ghostty et sera incluse dans une prochaine version (1.3)

---

Vue d’ensemble de la fuite mémoire de Ghostty

• Certains utilisateurs ont signalé que Ghostty utilisait plus de 37 Go de mémoire après être resté actif longtemps
  • La fuite existait au moins depuis la version 1.0, et des applications CLI récentes ont réuni certaines conditions qui ont révélé le problème
• Le correctif a déjà été fusionné sur GitHub et sera inclus dans les builds nightly et la version stable 1.3

Structure de PageList et gestion de la mémoire

• Ghostty utilise une structure de liste doublement chaînée appelée PageList pour stocker le contenu du terminal
  • Chaque page contient des données comme les caractères, les styles et les hyperliens
• Les pages sont allouées avec mmap et réutilisées via un pool de pages de taille standard
  • Les pages de taille inférieure ou égale à la taille standard sont renvoyées dans le pool
  • Les pages de taille non standard doivent être libérées directement avec munmap
• Cette structure n’avait rien d’anormal en soi, mais une erreur dans la logique d’optimisation a provoqué la fuite

Optimisation du scrollback et origine du bug

• Lorsque Ghostty dépasse scrollback-limit, il applique une optimisation consistant à réutiliser la page la plus ancienne
  • Les performances sont améliorées en ajustant simplement les pointeurs, sans allouer de nouvelle page
• Le problème vient du fait que, pendant ce processus, seules les métadonnées des pages non standard étaient modifiées pour indiquer une taille standard, alors que la mémoire réelle restait inchangée
  • Lors de la libération ultérieure, elles étaient alors prises pour des pages standard, et munmap n’était pas appelé
• Résultat : les pages non standard n’étaient jamais libérées et s’accumulaient, provoquant une fuite mémoire massive sur les longues sessions

Claude Code et la visibilité à grande échelle de la fuite

• Claude Code CLI produit fréquemment des sorties graphiques à points de code multiples, ce qui augmente la fréquence d’utilisation des pages non standard
  • En plus de cela, ses sorties de scrollback sont abondantes, ce qui accélère l’accumulation de la fuite
• Dans la conception de Ghostty, les pages non standard sont censées rester rares, mais les caractéristiques de Claude Code ont permis de reproduire massivement la fuite
• Le développeur précise que ce bug n’est pas un problème de Claude Code, mais bien un défaut de logique interne de Ghostty

Contenu du correctif

• La solution consiste à ne plus réutiliser les pages non standard et à les libérer immédiatement avec munmap
  • Si une page non standard est rencontrée dans le scrollback, une nouvelle page standard est réallouée depuis le pool
• Certains utilisateurs ont proposé une stratégie de réutilisation des pages non standard, mais une correction simple et sûre a été privilégiée dans l’immédiat
• Exemple de code du correctif :

  if (first.data.memory.len > std_size) {
      self.destroyNode(first);
      break :prune;
  }
  

Traçage de la fuite avec les tags VM

• La fonction de tags VM du noyau Mach sur macOS a été utilisée pour attribuer un tag spécifique aux allocations mémoire de PageList
  • En phase de débogage, cela permet d’identifier clairement les zones mémoire de Ghostty
  • Cela a grandement aidé à retracer l’origine de la fuite et à valider la correction
• Cette fonctionnalité permet de vérifier visuellement si la mémoire liée à PageList est bien libérée

Dispositif de prévention des fuites mémoire dans Ghostty

• Ghostty dispose déjà de plusieurs mécanismes pour détecter et prévenir les fuites
  • Utilisation de l’allocateur de détection de fuites de Zig dans les builds de débogage et les tests unitaires
  • Exécution de l’ensemble des tests avec valgrind dans la CI
  • Vérification des fuites dans le code Swift avec macOS Instruments
  • Validation des PR liées à GTK via des tests GUI Valgrind
• Cette fuite ne se produisait que dans des conditions très spécifiques, ce qui explique pourquoi les tests existants ne la reproduisaient pas
  • Un nouveau cas de test a été ajouté pour éviter toute régression

Conclusion

• Ce problème a été identifié comme le plus important cas de fuite mémoire observé jusqu’ici dans Ghostty
• Même après le correctif, un suivi continu via les signalements utilisateurs et les tests de reproduction est prévu
• Les données de diagnostic et les cas de reproduction fournis par la communauté ont joué un rôle décisif dans la résolution du problème
• Le texte souligne qu’obtenir un environnement reproductible est essentiel pour résoudre les fuites mémoire