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