OLD | NEW |
(Empty) | |
| 1 // Copyright 2017 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 CHROME_INSTALLER_UTIL_EXPERIMENT_STORAGE_H_ |
| 6 #define CHROME_INSTALLER_UTIL_EXPERIMENT_STORAGE_H_ |
| 7 |
| 8 #include <memory> |
| 9 |
| 10 #include "base/macros.h" |
| 11 #include "base/strings/string16.h" |
| 12 #include "base/win/scoped_handle.h" |
| 13 |
| 14 namespace installer { |
| 15 |
| 16 class Experiment; |
| 17 struct ExperimentMetrics; |
| 18 |
| 19 // Manages the storage of experiment state on the machine. |
| 20 // |
| 21 // Participation is a per-install property evaluated one time to determine |
| 22 // whether or not the install as a whole participates in the study. It is |
| 23 // stored in the install's ClientState key. |
| 24 // |
| 25 // ExperimentMetrics are stored in a per-install experiment_label, while the |
| 26 // fine-grained Experiment data are stored in a per-user key in Chrome's |
| 27 // ClientState or ClientStateMedium key. For system-level installs, metrics are |
| 28 // reported for only a single user on the machine, so only that one user will |
| 29 // participate in the experiment. |
| 30 // |
| 31 // Owing to this "metrics are per-install" property in the face of potentially |
| 32 // multiple users running the same install, ExperimentMetrics are considered the |
| 33 // source of truth for an install's participation in the experiment. For any |
| 34 // given state expressed in the experiment_label holding these metrics, there |
| 35 // should be matching Experiment data for precisely one user. |
| 36 // |
| 37 // As state is written across multiple locations in the registry, a global |
| 38 // mutex is used for all reads and writes to ensure consistent state. |
| 39 class ExperimentStorage { |
| 40 public: |
| 41 enum class Participation { |
| 42 // No participation state was found for the install. |
| 43 kNotEvaluated, |
| 44 |
| 45 // The client is not participating in the study. |
| 46 kNotParticipating, |
| 47 |
| 48 // The client is participating in the study. |
| 49 kIsParticipating, |
| 50 }; |
| 51 |
| 52 // Grants the holder exclusive access to the data in the registry. Consumers |
| 53 // are expected to not hold an instance across any blocking operations. |
| 54 class Lock { |
| 55 public: |
| 56 ~Lock(); |
| 57 |
| 58 // Reads the participation state for the install. Returns false in case of |
| 59 // error. |
| 60 bool ReadParticipation(Participation* participation); |
| 61 |
| 62 // Writes the participation state for the install. Returns false if the |
| 63 // write failed. |
| 64 bool WriteParticipation(Participation participation); |
| 65 |
| 66 // Loads the experiment metrics and data from the registry. Returns false if |
| 67 // the state in the registry corresponds to a different user or could not be |
| 68 // read. |
| 69 bool LoadExperiment(Experiment* experiment); |
| 70 |
| 71 // Stores the experiment metrics and data in |experiment| into the registry. |
| 72 bool StoreExperiment(const Experiment& experiment); |
| 73 |
| 74 // Loads per-install experiment metrics into |metrics|. Returns true if a |
| 75 // value was read or if none was found, in which case |metrics| is set to |
| 76 // the uninitialized state. Returns false in case of any error reading or |
| 77 // parsing the metrics. |
| 78 bool LoadMetrics(ExperimentMetrics* metrics); |
| 79 |
| 80 // Stores |metrics| in the per-install experiment_label. |
| 81 bool StoreMetrics(const ExperimentMetrics& metrics); |
| 82 |
| 83 private: |
| 84 friend ExperimentStorage; |
| 85 |
| 86 explicit Lock(ExperimentStorage* storage); |
| 87 |
| 88 ExperimentStorage* storage_; |
| 89 |
| 90 DISALLOW_COPY_AND_ASSIGN(Lock); |
| 91 }; |
| 92 |
| 93 ExperimentStorage(); |
| 94 ~ExperimentStorage(); |
| 95 |
| 96 // Returns exclusive access to the experiment storage. The underlying |
| 97 // ExperimentStorage instance must not be deleted while the Lock* returned |
| 98 // here is still in use. |
| 99 std::unique_ptr<Lock> AcquireLock(); |
| 100 |
| 101 private: |
| 102 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestEncodeDecodeMetrics); |
| 103 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestEncodeDecodeForMin); |
| 104 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestEncodeDecodeForMax); |
| 105 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestLoadStoreMetrics); |
| 106 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestLoadStoreExperiment); |
| 107 |
| 108 // Reads |bit_length| bits ending at |low_bit| of a 64 bit unsigned int into |
| 109 // an int. |
| 110 static int ReadUint64Bits(uint64_t source, int bit_length, int low_bit); |
| 111 |
| 112 // Sets the last |bit_length| bits of |value| into |target| at bit position |
| 113 // ending at low_bit. |
| 114 static void SetUint64Bits(int value, |
| 115 int bit_length, |
| 116 int low_bit, |
| 117 uint64_t* target); |
| 118 |
| 119 // Decodes |encoded_metrics| into |metrics|, return true on success. Returns |
| 120 // false if the encoding is malformed. |
| 121 static bool DecodeMetrics(base::StringPiece16 encoded_metrics, |
| 122 ExperimentMetrics* metrics); |
| 123 |
| 124 // Returns the encoded form of |metrics|. |
| 125 static base::string16 EncodeMetrics(const ExperimentMetrics& metrics); |
| 126 |
| 127 // Loads the per-install experiment metrics into |metrics|. Returns true if a |
| 128 // value was read or if none was found, in which case |metrics| is set to the |
| 129 // uninitialized state. Returns false in case of any error reading or parsing |
| 130 // the metrics. |
| 131 bool LoadMetricsUnsafe(ExperimentMetrics* metrics); |
| 132 |
| 133 // StoreMetrics without acquiring the mutex. |
| 134 bool StoreMetricsUnsafe(const ExperimentMetrics& metrics); |
| 135 |
| 136 // Loads the experiment state for the current user's Retention key into |
| 137 // |experiment|. Returns true if all values are read. Returns false otherwise, |
| 138 // in which case |experiment| is left in an undefined state. |
| 139 bool LoadStateUnsafe(Experiment* experiment); |
| 140 |
| 141 // Stores |experiment| in the current user's Retention key. |
| 142 bool StoreStateUnsafe(const Experiment& experiment); |
| 143 |
| 144 // A global mutex with a distinct name for the current installation. |
| 145 base::win::ScopedHandle mutex_; |
| 146 |
| 147 DISALLOW_COPY_AND_ASSIGN(ExperimentStorage); |
| 148 }; |
| 149 |
| 150 } // namespace installer |
| 151 |
| 152 #endif // CHROME_INSTALLER_UTIL_EXPERIMENT_STORAGE_H_ |
OLD | NEW |