components/variations/entropy_provider.h

   1 // Copyright (c) 2012 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 COMPONENTS_VARIATIONS_ENTROPY_PROVIDER_H_
   6 #define COMPONENTS_VARIATIONS_ENTROPY_PROVIDER_H_
   7
   8 #include <functional>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/basictypes.h"
  13 #include "base/compiler_specific.h"
  14 #include "base/metrics/field_trial.h"
  15 #include "third_party/mt19937ar/mt19937ar.h"
  16
  17 namespace metrics {
  18
  19 // Internals of entropy_provider.cc exposed for testing.
  20 namespace internal {
  21
  22 // A functor that generates random numbers based on a seed, using the Mersenne
  23 // Twister algorithm. Suitable for use with std::random_shuffle().
  24 struct SeededRandGenerator : std::unary_function<uint32, uint32> {
  25   explicit SeededRandGenerator(uint32 seed);
  26   ~SeededRandGenerator();
  27
  28   // Returns a random number in range [0, range).
  29   uint32 operator()(uint32 range);
  30
  31   MersenneTwister mersenne_twister_;
  32 };
  33
  34 // Fills |mapping| to create a bijection of values in the range of
  35 // [0, |mapping.size()|), permuted based on |randomization_seed|.
  36 void PermuteMappingUsingRandomizationSeed(uint32 randomization_seed,
  37                                           std::vector<uint16>* mapping);
  38
  39 }  // namespace internal
  40
  41 // SHA1EntropyProvider is an entropy provider suitable for high entropy
  42 // sources. It works by taking the first 64 bits of the SHA1 hash of the
  43 // entropy source concatenated with the trial name and using that for the
  44 // final entropy value.
  45 class SHA1EntropyProvider : public base::FieldTrial::EntropyProvider {
  46  public:
  47   // Creates a SHA1EntropyProvider with the given |entropy_source|, which
  48   // should contain a large amount of entropy - for example, a textual
  49   // representation of a persistent randomly-generated 128-bit value.
  50   explicit SHA1EntropyProvider(const std::string& entropy_source);
  51   virtual ~SHA1EntropyProvider();
  52
  53   // base::FieldTrial::EntropyProvider implementation:
  54   virtual double GetEntropyForTrial(const std::string& trial_name,
  55                                     uint32 randomization_seed) const OVERRIDE;
  56
  57  private:
  58   std::string entropy_source_;
  59
  60   DISALLOW_COPY_AND_ASSIGN(SHA1EntropyProvider);
  61 };
  62
  63 // PermutedEntropyProvider is an entropy provider suitable for low entropy
  64 // sources (below 16 bits). It uses the field trial name to generate a
  65 // permutation of a mapping array from an initial entropy value to a new value.
  66 // Note: This provider's performance is O(2^n), where n is the number of bits
  67 // in the entropy source.
  68 class PermutedEntropyProvider : public base::FieldTrial::EntropyProvider {
  69  public:
  70   // Creates a PermutedEntropyProvider with the given |low_entropy_source|,
  71   // which should have a value in the range of [0, low_entropy_source_max).
  72   PermutedEntropyProvider(uint16 low_entropy_source,
  73                           size_t low_entropy_source_max);
  74   virtual ~PermutedEntropyProvider();
  75
  76   // base::FieldTrial::EntropyProvider implementation:
  77   virtual double GetEntropyForTrial(const std::string& trial_name,
  78                                     uint32 randomization_seed) const OVERRIDE;
  79
  80  protected:
  81   // Performs the permutation algorithm and returns the permuted value that
  82   // corresponds to |low_entropy_source_|.
  83   virtual uint16 GetPermutedValue(uint32 randomization_seed) const;
  84
  85  private:
  86   uint16 low_entropy_source_;
  87   size_t low_entropy_source_max_;
  88
  89   DISALLOW_COPY_AND_ASSIGN(PermutedEntropyProvider);
  90 };
  91
  92 }  // namespace metrics
  93
  94 #endif  // COMPONENTS_VARIATIONS_ENTROPY_PROVIDER_H_