Improved iterator for persistent memory allocator.

base/metrics/persistent_histogram_allocator.h

 // Copyright 2016 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_PERSISTENCE_H_
 #define BASE_METRICS_HISTOGRAM_PERSISTENCE_H_
 
 #include <memory>
 
 #include "base/atomicops.h"
 #include "base/base_export.h"
 #include "base/feature_list.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 {
+  // A reference to a histogram. While this is implemented as PMA::Reference,
+  // it is not conceptually the same thing. Outside callers should always use
+  // a Reference matching the class it is for and not mix the two.
+  using Reference = PersistentMemoryAllocator::Reference;
+
+  // Iterator used for fetching persistent histograms from an allocator.
+  // It is lock-free and thread-safe.
+  // See PersistentMemoryAllocator::Iterator for more information.
+  class BASE_EXPORT Iterator {
    public:
-    bool is_clear() { return memory_iter.is_clear(); }
+    // Constructs an iterator on a given |allocator|, starting at the beginning.
+    // The allocator must live beyond the lifetime of the iterator.
+    explicit Iterator(PersistentHistogramAllocator* allocator);
+
+    // Gets the next histogram from persistent memory; returns null if there
+    // are no more histograms to be found. This may still be called again
+    // later to retrieve any new histograms added in the meantime.
+    std::unique_ptr<HistogramBase> GetNext() { return GetNextWithIgnore(0); }
+
+    // Gets the next histogram from persistent memory, ignoring one particular
+    // reference in the process. Pass |ignore| of zero (0) to ignore nothing.
+    std::unique_ptr<HistogramBase> GetNextWithIgnore(Reference ignore);
 
    private:
-    friend class PersistentHistogramAllocator;
+    // Weak-pointer to histogram allocator being iterated over.
+    PersistentHistogramAllocator* allocator_;
 
-    // The iterator used for stepping through persistent memory iterables.
-    PersistentMemoryAllocator::Iterator memory_iter;
+    // The iterator used for stepping through objects in persistent memory.
+    // It is lock-free and thread-safe which is why this class is also such.
+    PersistentMemoryAllocator::Iterator memory_iter_;
+
+    DISALLOW_COPY_AND_ASSIGN(Iterator);
   };
 
-  using Reference = PersistentMemoryAllocator::Reference;
-
   // A PersistentHistogramAllocator is constructed from a PersistentMemory-
   // Allocator object of which it takes ownership.
   PersistentHistogramAllocator(
       std::unique_ptr<PersistentMemoryAllocator> memory);
   virtual ~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.
   std::unique_ptr<HistogramBase> GetHistogram(Reference ref);
 
-  // Get the next histogram in persistent data based on iterator.
-  std::unique_ptr<HistogramBase> GetNextHistogram(Iterator* iter) {
-    return GetNextHistogramWithIgnore(iter, 0);
-  }
-
-  // Create an iterator for going through all histograms in an allocator.
-  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".
   std::unique_ptr<HistogramBase> AllocateHistogram(
       HistogramType histogram_type,
       const std::string& name,
       int minimum,
       int maximum,
       const BucketRanges* bucket_ranges,
       int32_t flags,
       Reference* ref_ptr);
@@ skipping 167 matching lines @@
   // Import always continues from where it left off, making use of a single
   // iterator to continue the work.
   Iterator import_iterator_;
 
   DISALLOW_COPY_AND_ASSIGN(GlobalHistogramAllocator);
 };
 
 }  // namespace base
 
 #endif  // BASE_METRICS_HISTOGRAM_PERSISTENCE_H_