MemPostings: comments on m & lvs

colega · colega · commit e61c8c9e55fb · 2024-11-20T15:49:41.000+01:00
Signed-off-by: Oleg Zaytsev &lt;mail@olegzaytsev.com&gt;
diff --git a/tsdb/index/postings.go b/tsdb/index/postings.go
@@ -57,9 +57,23 @@ var ensureOrderBatchPool = sync.Pool{
 // EnsureOrder() must be called once before any reads are done. This allows for quick
 // unordered batch fills on startup.
 type MemPostings struct {
-	mtx     sync.RWMutex
-	m       map[string]map[string][]storage.SeriesRef
-	lvs     map[string][]string
+	mtx sync.RWMutex
+
+	// m holds the postings lists for each label-value pair, indexed first by label name, and then by label value.
+	//
+	// mtx must be held when interacting with m (the appropriate one for reading or writing).
+	// It is safe to retain a reference to a postings list after releasing the lock.
+	//
+	// BUG: There's currently a data race in addFor, which might modify the tail of the postings list:
+	// https://github.com/prometheus/prometheus/issues/15317
+	m map[string]map[string][]storage.SeriesRef
+
+	// lvs holds the label values for each label name.
+	// lvs[name] is essentially an unsorted append-only list of all keys in m[name]
+	// mtx must be held when interacting with lvs.
+	// Since it's append-only, it is safe to the label values slice after releasing the lock.
+	lvs map[string][]string
+
 	ordered bool
 }
 
