1 // Copyright 2018 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef BASE_METRICS_PERSISTENT_HISTOGRAM_STORAGE_H_
6 #define BASE_METRICS_PERSISTENT_HISTOGRAM_STORAGE_H_
7 
8 #include "base/base_export.h"
9 #include "base/files/file_path.h"
10 #include "base/macros.h"
11 #include "base/strings/string_piece.h"
12 
13 namespace base {
14 
15 // This class creates a fixed sized persistent memory to allow histograms to be
16 // stored in it. When a PersistentHistogramStorage is destructed, histograms
17 // recorded during its lifetime are persisted in the directory
18 // |storage_base_dir_|/|allocator_name| (see the ctor for allocator_name).
19 // Histograms are not persisted if the storage directory does not exist on
20 // destruction. PersistentHistogramStorage should be instantiated as early as
21 // possible in the process lifetime and should never be instantiated again.
22 // Persisted histograms will eventually be reported by Chrome.
23 class BASE_EXPORT PersistentHistogramStorage {
24  public:
25   enum class StorageDirManagement { kCreate, kUseExisting };
26 
27   // Creates a process-wide storage location for histograms that will be written
28   // to a file within a directory provided by |set_storage_base_dir()| on
29   // destruction.
30   // The |allocator_name| is used both as an internal name for the allocator,
31   // well as the leaf directory name for the file to which the histograms are
32   // persisted. The string must be ASCII.
33   // |storage_dir_management| specifies if this instance reuses an existing
34   // storage directory, or is responsible for creating one.
35   PersistentHistogramStorage(StringPiece allocator_name,
36                              StorageDirManagement storage_dir_management);
37 
38   ~PersistentHistogramStorage();
39 
40   // The storage directory isn't always known during initial construction so
41   // it's set separately. The last one wins if there are multiple calls to this
42   // method.
set_storage_base_dir(const FilePath & storage_base_dir)43   void set_storage_base_dir(const FilePath& storage_base_dir) {
44     storage_base_dir_ = storage_base_dir;
45   }
46 
47   // Disables histogram storage.
Disable()48   void Disable() { disabled_ = true; }
49 
50  private:
51   // Metrics files are written into directory
52   // |storage_base_dir_|/|allocator_name| (see the ctor for allocator_name).
53   FilePath storage_base_dir_;
54 
55   // The setting of the storage directory management.
56   const StorageDirManagement storage_dir_management_;
57 
58   // A flag indicating if histogram storage is disabled. It starts with false,
59   // but can be set to true by the caller who decides to throw away its
60   // histogram data.
61   bool disabled_ = false;
62 
63   DISALLOW_COPY_AND_ASSIGN(PersistentHistogramStorage);
64 };
65 
66 }  // namespace base
67 
68 #endif  // BASE_METRICS_PERSISTENT_HISTOGRAM_STORAGE_H_
69