Refactor histogram_persistence to be a class.

base/metrics/persistent_histogram_allocator.h

+// Copyright (c) 2016 The Chromium Authors. All rights reserved.

[Alexei Svitkine (slow), 2016/03/15 22:00:10]

No (c)

[bcwhite, 2016/03/16 00:32:38]

Done.

+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BASE_METRICS_HISTOGRAM_PERSISTENCE_H_
+#define BASE_METRICS_HISTOGRAM_PERSISTENCE_H_
+
+#include "base/atomicops.h"
+#include "base/base_export.h"
+#include "base/feature_list.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/memory/shared_memory.h"
+#include "base/metrics/histogram_base.h"
+#include "base/metrics/persistent_memory_allocator.h"
+#include "base/strings/string_piece.h"
+
+namespace base {
+
+// Feature definition for enabling histogram persistence.
+BASE_EXPORT extern const Feature kPersistentHistogramsFeature;
+
+// This class manages histograms created within a PersistentMemoryAllocator.
+class BASE_EXPORT PersistentHistogramAllocator {
+ public:
+  // This iterator is used for fetching persistent histograms from an allocator.
+  class Iterator {
+   public:
+    bool is_clear() { return memory_iter.is_clear(); }
+
+   private:
+    friend class PersistentHistogramAllocator;
+
+    // The iterator used for stepping through persistent memory iterables.
+    PersistentMemoryAllocator::Iterator memory_iter;
+  };
+
+  using Reference = PersistentMemoryAllocator::Reference;
+
+  // A PersistentHistogramAllocator is constructed from a PersistentMemory-
+  // Allocator object of which it takes ownership.
+  PersistentHistogramAllocator(scoped_ptr<PersistentMemoryAllocator> memory);
+  ~PersistentHistogramAllocator();
+
+  // Direct access to underlying memory allocator. If the segment is shared
+  // across threads or processes, reading data through these values does
+  // not guarantee consistency. Use with care. Do not write.
+  PersistentMemoryAllocator* memory_allocator() {
+    return memory_allocator_.get();
+  }
+
+  // Implement the "metadata" API of a PersistentMemoryAllocator, forwarding
+  // those requests to the real one.
+  uint64_t Id() const { return memory_allocator_->Id(); }
+  const char* Name() const { return memory_allocator_->Name(); }
+  const void* data() const { return memory_allocator_->data(); }
+  size_t length() const { return memory_allocator_->length(); }
+  size_t used() const { return memory_allocator_->used(); }
+
+  // Recreate a Histogram from data held in persistent memory. Though this
+  // object will be local to the current process, the sample data will be
+  // shared with all other threads referencing it. This method takes a |ref|
+  // to where the top-level histogram data may be found in this allocator.
+  // This method will return null if any problem is detected with the data.
+  scoped_ptr<HistogramBase> GetHistogram(Reference ref);
+
+  // Get the next histogram in persistent data based on iterator.
+  scoped_ptr<HistogramBase> GetNextHistogram(Iterator* iter) {
+    return GetNextHistogramWithIgnore(iter, 0);
+  }
+
+  // Create an iterator for going through all histograms in an allocator.

[Alexei Svitkine (slow), 2016/03/15 22:00:10]

You were planning to refactor the iterators in an upcoming CL? Add a TODO.

[bcwhite, 2016/03/16 00:32:38]

Already done:
https://codereview.chromium.org/1803253002

+  void CreateIterator(Iterator* iter);
+
+  // Allocate a new persistent histogram. The returned histogram will not
+  // be able to be located by other allocators until it is "finalized".
+  scoped_ptr<HistogramBase> AllocateHistogram(
+      HistogramType histogram_type,
+      const std::string& name,
+      int minimum,
+      int maximum,
+      const BucketRanges* bucket_ranges,
+      int32_t flags,
+      Reference* ref_ptr);
+
+  // Finalize the creation of the histogram, making it available to other
+  // processes if |register| is True, forgetting it otherwise.
+  void FinalizeHistogram(Reference ref, bool register);

[Alexei Svitkine (slow), 2016/03/15 22:00:10]

Nit: "register" can be a keyword in C++ and gets syntax highlighted here. Use a
different name to avoid confusion - e.g. bool should_register

[bcwhite, 2016/03/16 00:32:38]

Oops.  I'd already fixed it in the .cc file.  Odd that it's not a compiler
error.

+
+  // Create internal histograms for tracking memory use and allocation sizes
+  // for allocator of |name| (which can simply be the result of Name()). This
+  // is done seperately from construction for situations such as when the
+  // histograms will be backed by memory provided by this very allocator.
+  //
+  // IMPORTANT: Callers must update tools/metrics/histograms/histograms.xml
+  // with the following histograms:
+  //    UMA.PersistentAllocator.name.Allocs
+  //    UMA.PersistentAllocator.name.UsedPct
+  void CreateTrackingHistograms(StringPiece name);
+  void UpdateTrackingHistograms();
+
+  // Manage a PersistentHistogramAllocator for globally storing histograms in
+  // a space that can be persisted or shared between processes. There is only
+  // ever one allocator for all such histograms created by a single process.
+  // This takes ownership of the object and should be called as soon as
+  // possible during startup to capture as many histograms as possible and
+  // while operating single-threaded so there are no race-conditions.
+  static void SetGlobalAllocator(
+      scoped_ptr<PersistentHistogramAllocator> allocator);
+  static PersistentHistogramAllocator* GetGlobalAllocator();
+
+  // This access to the persistent allocator is only for testing; it extracts
+  // the current allocator completely. This allows easy creation of histograms
+  // within persistent memory segments which can then be extracted and used
+  // in other ways.
+  static scoped_ptr<PersistentHistogramAllocator>
+  ReleaseGlobalAllocatorForTesting();
+
+  // These helper methods perform SetGlobalAllocator() calls with allocators
+  // of the specified type and parameters.
+  static void CreateGlobalAllocatorOnPersistentMemory(
+      void* base,
+      size_t size,
+      size_t page_size,
+      uint64_t id,
+      StringPiece name);
+  static void CreateGlobalAllocatorOnLocalMemory(
+      size_t size,
+      uint64_t id,
+      StringPiece name);
+  static void CreateGlobalAllocatorOnSharedMemory(
+      size_t size,
+      const SharedMemoryHandle& handle);
+
+  // Import new histograms from the global PersistentHistogramAllocator. It's
+  // possible for other processes to create histograms in the active memory
+  // segment; this adds those to the internal list of known histograms to
+  // avoid creating duplicates that would have to be merged during reporting.
+  // Every call to this method resumes from the last entry it saw; it costs
+  // nothing if nothing new has been added.
+  static void ImportGlobalHistograms();
+
+  // Histogram containing creation results. Visible for testing.
+  static HistogramBase* GetCreateHistogramResultHistogram();
+
+ private:
+  // Enumerate possible creation results for reporting.
+  enum CreateHistogramResultType {
+    // Everything was fine.
+    CREATE_HISTOGRAM_SUCCESS = 0,
+
+    // Pointer to metadata was not valid.
+    CREATE_HISTOGRAM_INVALID_METADATA_POINTER,
+
+    // Histogram metadata was not valid.
+    CREATE_HISTOGRAM_INVALID_METADATA,
+
+    // Ranges information was not valid.
+    CREATE_HISTOGRAM_INVALID_RANGES_ARRAY,
+
+    // Counts information was not valid.
+    CREATE_HISTOGRAM_INVALID_COUNTS_ARRAY,
+
+    // Could not allocate histogram memory due to corruption.
+    CREATE_HISTOGRAM_ALLOCATOR_CORRUPT,
+
+    // Could not allocate histogram memory due to lack of space.
+    CREATE_HISTOGRAM_ALLOCATOR_FULL,
+
+    // Could not allocate histogram memory due to unknown error.
+    CREATE_HISTOGRAM_ALLOCATOR_ERROR,
+
+    // Histogram was of unknown type.
+    CREATE_HISTOGRAM_UNKNOWN_TYPE,
+
+    // Instance has detected a corrupt allocator (recorded only once).
+    CREATE_HISTOGRAM_ALLOCATOR_NEWLY_CORRUPT,
+
+    // Always keep this at the end.
+    CREATE_HISTOGRAM_MAX
+  };
+
+  // The structure used to hold histogram data in persistent memory. It is
+  // defined and used entirely within the .cc file.
+  struct PersistentHistogramData;
+
+  // Get the next histogram in persistent data based on iterator while
+  // ignoring a particular reference if it is found.
+  scoped_ptr<HistogramBase> GetNextHistogramWithIgnore(
+      Iterator* iter,
+      Reference ignore);
+
+  // Create a histogram based on saved (persistent) information about it.
+  scoped_ptr<HistogramBase> CreateHistogram(
+      PersistentHistogramData* histogram_data_ptr);
+
+  // Record the result of a histogram creation.
+  static void RecordCreateHistogramResult(CreateHistogramResultType result);
+
+  // The memory allocator that provides the actual histogram storage.
+  scoped_ptr<PersistentMemoryAllocator> memory_allocator_;
+
+  // A reference to the last-created histogram in the allocator, used to avoid
+  // trying to import what was just created.
+  subtle::AtomicWord last_created_ = 0;
+
+  DISALLOW_COPY_AND_ASSIGN(PersistentHistogramAllocator);
+};
+
+}  // namespace base
+
+#endif  // BASE_METRICS_HISTOGRAM_PERSISTENCE_H_