Update potential misunderstanding about thread safety

src/metric.hpp

@@ -55,16 +55,17 @@ template <typename T> struct Family;
 // render() mutex - no need to be thread-safe internally
 template <typename T> using MetricCallback = std::function<double()>;
 
-// Counter: Monotonically increasing metric with single-writer semantics
-// Use for: request counts, error counts, bytes processed, etc.
+// Counter: A metric value that only increases.
 //
-// THREAD SAFETY: Each counter instance has exactly ONE writer thread (the one
-// that created it). It is an error to call inc() from any thread other than the
-// creating thread. Multiple readers can safely read the value from other
-// threads.
+// THREAD SAFETY RULES:
+// 1. Do not call inc() on the same Counter object from multiple threads.
+//    Each object must have only one writer thread.
+// 2. To use Counters concurrently, each thread must create its own Counter
+//    object.
+// 3. When rendered, the values of all Counter objects with the same labels
+//    are summed together into a single total.
 struct Counter {
-  void
-  inc(double = 1.0); // Increment counter (must be >= 0) - SINGLE WRITER ONLY
+  void inc(double = 1.0); // Increment counter (must be >= 0)
 
 private:
   Counter();
@@ -74,17 +75,20 @@ private:
   State *p;
 };
 
-// Gauge: Can increase/decrease metric
-// Use for: memory usage, active connections, queue depth, etc.
+// Gauge: A metric value that can be set, increased, or decreased.
 //
-// THREAD SAFETY: Each gauge instance has exactly ONE writer thread (the one
-// that created it). It is an error to call inc()/dec()/set() from any thread
-// other than the creating thread.
-// IMPLEMENTATION NOTE: Mutex protection is an internal implementation detail.
+// THREAD SAFETY RULES:
+// 1. Do not call inc(), dec(), or set() on the same Gauge object from
+//    multiple threads. Each object must have only one writer thread.
+// 2. To use Gauges concurrently, each thread must create its own Gauge object.
+// 3. If multiple Gauge objects are created with the same labels, their
+//    operations are combined. For example, increments from different objects
+//    are cumulative.
+// 4. For independent gauges, create them with unique labels.
 struct Gauge {
-  void inc(double = 1.0); // Increase gauge value - SINGLE WRITER ONLY
-  void dec(double = 1.0); // Decrease gauge value - SINGLE WRITER ONLY
-  void set(double);       // Set absolute value - SINGLE WRITER ONLY
+  void inc(double = 1.0);
+  void dec(double = 1.0);
+  void set(double);
 
 private:
   Gauge();
@@ -94,17 +98,17 @@ private:
   State *p;
 };
 
-// Histogram: Distribution tracking with single-writer semantics
-// Use for: request latency, response size, processing time, etc.
-// Buckets are automatically sorted, deduplicated, and include +Inf
+// Histogram: A metric that samples observations into buckets.
 //
-// THREAD SAFETY: Each histogram instance has exactly ONE writer thread (the one
-// that created it). It is an error to call observe() from any thread other than
-// the creating thread. Multiple readers can safely read bucket values from
-// other threads.
+// THREAD SAFETY RULES:
+// 1. Do not call observe() on the same Histogram object from multiple
+//    threads. Each object must have only one writer thread.
+// 2. To use Histograms concurrently, each thread must create its own
+//    Histogram object.
+// 3. When rendered, the observations from all Histogram objects with the
+//    same labels are combined into a single histogram.
 struct Histogram {
-  void observe(
-      double); // Record observation in appropriate bucket - SINGLE WRITER ONLY
+  void observe(double); // Record observation in appropriate bucket
 
 private:
   Histogram();