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. |
| 97 std::unique_ptr<Lock> AcquireLock(); |
| 98 |
| 99 private: |
| 100 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestEncodeDecodeMetrics); |
| 101 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestEncodeDecodeForMin); |
| 102 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestEncodeDecodeForMax); |
| 103 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestLoadStoreMetrics); |
| 104 FRIEND_TEST_ALL_PREFIXES(ExperimentStorageTest, TestLoadStoreExperiment); |
| 105 |
| 106 // Reads |len| bits ending at |low_bit| of a 64 bit unsigned int into an int. |
| 107 static int ReadUint64Bits(uint64_t source, int low_bit, int len); |
| 108 |
| 109 // Sets the last |len| bits of |value| into |source| at bit position |
| 110 // ending at low_bit. |
| 111 static void SetUint64Bits(int value, int len, int low_bit, uint64_t* source); |
| 112 |
| 113 // Decodes |encoded_metrics| into |metrics|, return true on success. Returns |
| 114 // false if the encoding is malformed. |
| 115 static bool DecodeMetrics(base::StringPiece16 encoded_metrics, |
| 116 ExperimentMetrics* metrics); |
| 117 |
| 118 // Returns the encoded form of |metrics|. |
| 119 static base::string16 EncodeMetrics(const ExperimentMetrics& metrics); |
| 120 |
| 121 // Loads the per-install experiment metrics into |metrics|. Returns true if a |
| 122 // value was read or if none was found, in which case |metrics| is set to the |
| 123 // uninitialized state. Returns false in case of any error reading or parsing |
| 124 // the metrics. |
| 125 bool LoadMetricsUnsafe(ExperimentMetrics* metrics); |
| 126 |
| 127 // StoreMetrics without acquiring the mutex. |
| 128 bool StoreMetricsUnsafe(const ExperimentMetrics& metrics); |
| 129 |
| 130 // Loads the experiment state for the current user's Retention key into |
| 131 // |experiment|. Returns true if all values are read. Returns false otherwise, |
| 132 // in which case |experiment| is left in an undefined state. |
| 133 bool LoadStateUnsafe(Experiment* experiment); |
| 134 |
| 135 // Stores |experiment| in the current user's Retention key. |
| 136 bool StoreStateUnsafe(const Experiment& experiment); |
| 137 |
| 138 // A global mutex with a distinct name for the current installation. |
| 139 base::win::ScopedHandle mutex_; |
| 140 |
| 141 DISALLOW_COPY_AND_ASSIGN(ExperimentStorage); |
| 142 }; |
| 143 |
| 144 } // namespace installer |
| 145 |
| 146 #endif // CHROME_INSTALLER_UTIL_EXPERIMENT_STORAGE_H_ |
OLD | NEW |