Embed a single sample in histogram metadata.

base/metrics/histogram_samples.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_METRICS_HISTOGRAM_SAMPLES_H_
 #define BASE_METRICS_HISTOGRAM_SAMPLES_H_
 
 #include <stddef.h>
 #include <stdint.h>
 
 #include <memory>
 
 #include "base/atomicops.h"
 #include "base/macros.h"
 #include "base/metrics/histogram_base.h"
 
 namespace base {
 
 class Pickle;
 class PickleIterator;
 class SampleCountIterator;
 
 // HistogramSamples is a container storing all samples of a histogram. All
 // elements must be of a fixed width to ensure 32/64-bit interoperability.
 // If this structure changes, bump the version number for kTypeIdHistogram
 // in persistent_histogram_allocator.cc.
+//
+// Note that though these samples are individually consistent (through the use
+// of atomic operations on the counts), there is only "eventual consistency"
+// overall when multiple threads are accessing this data. That means that the
+// sum, redundant-count, etc. could be momentarily out-of-sync with the stored
+// counts but will settle to a consistent "steady state" once all threads have
+// exited this code.
 class BASE_EXPORT HistogramSamples {
  public:
+  // A single value and count. To fit within a single atomic on 32-bit build
+  // architectures, both |value| and |count| are reduced in size to 16 bits.
+  // This limits the functionality somewhat but if an entry can't fit then
+  // the full array of samples can be allocated and used.
+  struct SingleSample {
+    int16_t value;
+    int16_t count;

[Alexei Svitkine (slow), 2017/04/12 17:38:07]

Have you considered making them mutually exclusive?

e.g. have a bit indicate whether it's one or the other. Then, have the remaining
31 bits hold the value - either of the single sample - or the count.

The relevant bit could be just the sign bit to make checks simple and so it can
just be an int32_t. (Though we should then be careful to never overflow max
int32_t and flip the bit unintentionally - which would require extra overflow
checks - which I think would be good to have regardless).

[bcwhite, 2017/04/13 00:06:01]

They can't be mutually exclusive because both are used together.  You can't have
a "count" without a "value".  There has to be something to which the count
applies.

It could be split differently (like 8/24) using a bit-field but I thought this
was cleaner.

[Alexei Svitkine (slow), 2017/04/18 20:52:19]

Per offline discussion, 16/16 seems to produce good results - so sticking with
this SGTM. Can you expand the comment to explicitly mention both use cases?
(e.g. a single value logged to a numeric histogram and and enum histogram being
recorded multiple times with a single value - like a success)

[bcwhite, 2017/04/19 18:13:01]

Done.

+  };
+
+  // A structure for managing an atomic single sample. Because this is generally
+  // used in association with other atomic values, the defined methods use
+  // acquire/release operations to guarantee ordering with outside values.
+  union AtomicSingleSample {
+    AtomicSingleSample() : as_atomic(0) {}
+    AtomicSingleSample(subtle::Atomic32 rhs) : as_atomic(rhs) {}
+
+    // Returns the single value in an atomic manner. This in an "acquire"
+    // load. The returned value isn't shared and thus its parts can be safely
+    // accessed.
+    SingleSample Load() const;
+
+    // Extracts the single value in an atomic manner. If |disable| is true then
+    // the single-sample will be set so it can never accumulate another value.
+    // This is "no barrier" so doesn't enforce ordering with other atomic ops.
+    SingleSample Extract(bool disable);
+
+    // Adds a given count to the held value. If not possible, it returns false
+    // and leaves the internal value unchanged. This in an "acquire/release"
+    // operation. Once extracted/disabled, this always returns false.
+    bool Accumulate(HistogramBase::Sample value, HistogramBase::Count count);
+
+   private:
+    // The actual sample value and count.
+    SingleSample as_parts;
+
+    // The sample as an atomic value. Atomic64 would provide more flexibility
+    // but isn't available on all builds.
+    subtle::Atomic32 as_atomic;
+  };
+
   struct Metadata {
     // Expected size for 32/64-bit check.
     static constexpr size_t kExpectedInstanceSize = 24;
 
     // Initialized when the sample-set is first created with a value provided
     // by the caller. It is generally used to identify the sample-set across
     // threads and processes, though not necessarily uniquely as it is possible
     // to have multiple sample-sets representing subsets of the data.
     uint64_t id;
 
@@ skipping 12 matching lines @@
 
     // A "redundant" count helps identify memory corruption. It redundantly
     // stores the total number of samples accumulated in the histogram. We
     // can compare this count to the sum of the counts (TotalCount() function),
     // and detect problems. Note, depending on the implementation of different
     // histogram types, there might be races during histogram accumulation
     // and snapshotting that we choose to accept. In this case, the tallies
     // might mismatch even when no memory corruption has happened.
     HistogramBase::AtomicCount redundant_count;
 
-    // 4 bytes of padding to explicitly extend this structure to a multiple of
-    // 64-bits. This is required to ensure the structure is the same size on
-    // both 32-bit and 64-bit builds.
-    char padding[4];
+    // A single histogram value and associated count. This allows histograms
+    // that typically report only a single value to not require full storage
+    // to be allocated.
+    AtomicSingleSample single_sample;  // 32 bits
   };
 
   // Because sturctures held in persistent memory must be POD, there can be no
   // default constructor to clear the fields. This derived class exists just
   // to clear them when being allocated on the heap.
-  struct LocalMetadata : Metadata {
-    LocalMetadata() {
-      id = 0;
-      sum = 0;
-      redundant_count = 0;
-    }
+  struct BASE_EXPORT LocalMetadata : Metadata {
+    LocalMetadata();
   };
 
   explicit HistogramSamples(uint64_t id);
   HistogramSamples(uint64_t id, Metadata* meta);
   virtual ~HistogramSamples();
 
   virtual void Accumulate(HistogramBase::Sample value,
                           HistogramBase::Count count) = 0;
   virtual HistogramBase::Count GetCount(HistogramBase::Sample value) const = 0;
   virtual HistogramBase::Count TotalCount() const = 0;
@@ skipping 19 matching lines @@
   }
   HistogramBase::Count redundant_count() const {
     return subtle::NoBarrier_Load(&meta_->redundant_count);
   }
 
  protected:
   // Based on |op| type, add or subtract sample counts data from the iterator.
   enum Operator { ADD, SUBTRACT };
   virtual bool AddSubtractImpl(SampleCountIterator* iter, Operator op) = 0;
 
-  void IncreaseSum(int64_t diff);
-  void IncreaseRedundantCount(HistogramBase::Count diff);
+  bool AccumulateSingleSample(HistogramBase::Sample value,
+                              HistogramBase::Count count);
+
+  void IncreaseSumAndCount(int64_t sum, HistogramBase::Count count);
+
+  AtomicSingleSample& single_sample() { return meta_->single_sample; }
+  const AtomicSingleSample& single_sample() const {
+    return meta_->single_sample;
+  }
 
  private:
   // In order to support histograms shared through an external memory segment,
   // meta values may be the local storage or external storage depending on the
   // wishes of the derived class.
   LocalMetadata local_meta_;
   Metadata* meta_;
 
   DISALLOW_COPY_AND_ASSIGN(HistogramSamples);
 };
@@ skipping 11 matching lines @@
   virtual void Get(HistogramBase::Sample* min,
                    HistogramBase::Sample* max,
                    HistogramBase::Count* count) const = 0;
 
   // Get the index of current histogram bucket.
   // For histograms that don't use predefined buckets, it returns false.
   // Requires: !Done();
   virtual bool GetBucketIndex(size_t* index) const;
 };
 
+class BASE_EXPORT SingleSampleIterator : public SampleCountIterator {
+ public:
+  SingleSampleIterator(HistogramBase::Sample min,
+                       HistogramBase::Sample max,
+                       HistogramBase::Count count);
+  SingleSampleIterator(HistogramBase::Sample min,
+                       HistogramBase::Sample max,
+                       HistogramBase::Count count,
+                       size_t bucket_index);
+  ~SingleSampleIterator() override;
+
+  // SampleCountIterator implementation:
+  bool Done() const override;
+  void Next() override;
+  void Get(HistogramBase::Sample* min,
+           HistogramBase::Sample* max,
+           HistogramBase::Count* count) const override;
+
+  // SampleVector uses predefined buckets, so iterator can return bucket index.
+  bool GetBucketIndex(size_t* index) const override;
+
+ private:
+  // Information about the single value to return.
+  const HistogramBase::Sample min_;
+  const HistogramBase::Sample max_;
+  const size_t bucket_index_;
+  HistogramBase::Count count_;
+};
+
 }  // namespace base
 
 #endif  // BASE_METRICS_HISTOGRAM_SAMPLES_H_