Deux goroutines qui écrivent dans la même map[string]int au même moment, et le programme s’arrête net avec fatal error: concurrent map writes.
Pas de panic récupérable, pas de stack trace applicative à intercepter. Juste l’arrêt.
Ce dernier article de la série regarde pourquoi le runtime réagit comme ça, et ce qu’il faut poser à la place.
Le premier article a décrit la structure interne d’une map, le deuxième sa croissance. Ici, on s’arrête sur ce qui se passe quand plusieurs goroutines y touchent en même temps.
💡 Tout le code de la série est sur github.
Le crash n’est pas un panic ordinaire
Le runtime Go pose un flag writing sur chaque map.
Chaque écriture le bascule au début de l’opération et le rebascule à la fin, via un XOR sur un bit dédié. Si une deuxième écriture arrive alors que le flag est déjà posé, le runtime en conclut qu’il y a un accès concurrent et déclenche un fatal error.
Ce n’est pas une panic classique. recover() ne rattrape rien : le programme s’arrête, point final. C’est un choix délibéré du runtime : corrompre silencieusement une structure de données partagée serait pire qu’un crash net.
func main() {
m := make(map[int]int)
var wg sync.WaitGroup
wg.Add(2)
writer := func(start int) {
defer wg.Done()
defer func() {
if r := recover(); r != nil {
fmt.Println("recover a intercepté:", r)
}
}()
for i := range 1000 {
m[start+i] = i
}
}
go writer(0)
go writer(1000)
wg.Wait()
fmt.Println("terminé sans crash, taille finale:", len(m))
}
fatal error: concurrent map writes
goroutine 19 [running]:
internal/runtime/maps.fatal(...)
[...]
exit status 2
Le recover est posé directement dans writer, la goroutine qui écrit effectivement dans la map. Ça ne change rien au résultat. La ligne « recover a intercepté » n’apparaît jamais, et la ligne « terminé sans crash » non plus, car le fatal error arrête tout le programme avant que wg.Wait() ne rende la main.
Cette détection reste du best-effort. Le flag writing n’attrape que les écritures qui se chevauchent assez longtemps pour que le runtime les voie. Une map peut très bien être corrompue sans que le programme crashe, simplement parce que le timing a épargné le flag.
Pour ça, il y a le race detector. Avec -race, chaque accès mémoire est instrumenté et les data races sont repérées sans dépendre du flag, lectures concurrentes à une écriture comprises (elles ne déclenchent pas toujours le fatal error).
Le flag est un dernier filet, pas un détecteur.
La preuve : relancez la démo avec -race et le fatal error disparaît le plus souvent. À la place, le race detector affiche WARNING: DATA RACE et sort avec le code 66.
👉 C’est lui qu’il faut brancher en CI, sur tous les tests qui touchent une map partagée.
Mutex, RWMutex ou sync.Map : la question à se poser d’abord
Trois options s’offrent pour protéger une map partagée. Le choix dépend de deux choses : le ratio lectures/écritures, et la forme de l’accès.
Mutex + map classique est le choix par défaut.
Une seule primitive à comprendre 👉 un verrou qui protège toute opération, lecture comme écriture.
type SafeCounter struct {
mu sync.Mutex
m map[string]int
}
func (c *SafeCounter) Inc(key string) {
c.mu.Lock()
defer c.mu.Unlock()
if c.m == nil {
c.m = make(map[string]int)
}
c.m[key]++
}
La vérification de c.m == nil évite un piège classique : la valeur zéro d’un SafeCounter a une map nil, et écrire dans une map nil panique. L’initialiser à la volée dans Inc rend la valeur zéro directement utilisable, sans constructeur à appeler avant le premier usage.
RWMutex + map classique autorise plusieurs lecteurs simultanés tant qu’aucune écriture n’est en cours. Ça vaut le coup quand les lectures dominent largement et que la section critique de lecture n’est pas triviale. Mais un RWMutex a un coût propre : maintenir le compteur de lecteurs, arbitrer entre lecteurs et writers en attente. Sur une section critique très courte, ce coût peut dépasser le bénéfice du parallélisme en lecture. Il n’y a pas de règle générale ici : ça se mesure sur le cas réel, avec un benchmark.
sync.Map est une structure spécialisée, pas un remplacement générique de map + verrou. La documentation officielle est explicite et cible deux cas d’usage précis :
- une clé écrite une fois puis lue de nombreuses fois (des caches qui ne grossissent qu’en append) ;
- plusieurs goroutines qui lisent, écrivent et réécrivent des jeux de clés disjoints, sans se marcher dessus.
En dehors de ces deux cas, la doc recommande explicitement une map classique avec verrou séparé.
type User struct {
ID string
Name string
}
func syncMapStoreAndLoadExample(user User) (User, bool) {
var cache sync.Map
cache.Store("user:42", user)
v, ok := cache.Load("user:42")
if !ok {
return User{}, false
}
return v.(User), true
}
Go 1.24 a réécrit l’implémentation interne de sync.Map avec une structure de type HashTrieMap. Les benchmarks publiés avant cette version, y compris ceux qu’on trouve dans d’anciens articles, ne reflètent donc plus le comportement actuel.
Le dépôt d’exemples qui accompagne cette série contient un benchmark comparant Mutex, RWMutex et sync.Map sur quatre ratios de lecture/écriture (0, 10, 50 et 90 % d’écritures), dans article3/bench_test.go.
Voici ce que ça donne avec Go 1.27.1 sur un Apple M5 Max (18 cœurs), médiane de trois passes de go test -bench . -count=3.
Les valeurs sont en ns/op, donc plus c’est bas, mieux c’est.
| Écritures | Mutex |
RWMutex |
sync.Map |
|---|---|---|---|
| 0 % | 77,7 | 52,7 | 1,1 |
| 10 % | 82,1 | 39,9 | 8,8 |
| 50 % | 86,8 | 52,4 | 31,7 |
| 90 % | 88,3 | 102,4 | 48,7 |
sync.Map gagne partout ici, et de loin en lecture.
Il faut lire ce résultat avec son contexte : le benchmark n’utilise que 100 clés, toutes insérées avant la mesure, et ne fait que réécrire des clés existantes. C’est exactement le terrain où sync.Map est à l’aise. Il ne dit rien d’une map qui reçoit en continu de nouvelles clés, que je n’ai pas mesurée.
À l’inverse, RWMutex bat Mutex tant que les écritures restent minoritaires, puis passe derrière à 90 %. Ces chiffres bougent d’une version de Go et d’une machine à l’autre : relancez le benchmark chez vous avant de trancher.
Ce qu’il faut faire maintenant
Une map accessible depuis plusieurs goroutines 👉 commence par un Mutex simple.
Le RWMutex vient ensuite, seulement si un profil ou un benchmark désigne la contention en lecture comme le goulot.
sync.Map ne se justifie que si l’accès correspond à l’un des deux cas décrits par la doc.
Enfin go test -race sur tout ce qui touche une map partagée, plutôt que de découvrir le fatal error en production 🫠.
📚 Liens
- Key Lookup and Concurrency in Go Maps: From Syntax to hmap
(⚠️ l’explication de l’ordre d’itération y est erronée, voir le deuxième article) - Go runtime : src/internal/runtime/maps
- Go 1.24 Release Notes
- sync.Map
