| OLD | NEW |
| 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
| 3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
| 4 | 4 |
| 5 // FieldTrial is a class for handling details of statistical experiments | 5 // FieldTrial is a class for handling details of statistical experiments |
| 6 // performed by actual users in the field (i.e., in a shipped or beta product). | 6 // performed by actual users in the field (i.e., in a shipped or beta product). |
| 7 // All code is called exclusively on the UI thread currently. | 7 // All code is called exclusively on the UI thread currently. |
| 8 // | 8 // |
| 9 // The simplest example is an experiment to see whether one of two options | 9 // The simplest example is an experiment to see whether one of two options |
| 10 // produces "better" results across our user population. In that scenario, UMA | 10 // produces "better" results across our user population. In that scenario, UMA |
| (...skipping 248 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 259 // untouched. | 259 // untouched. |
| 260 bool GetActiveGroup(ActiveGroup* active_group) const; | 260 bool GetActiveGroup(ActiveGroup* active_group) const; |
| 261 | 261 |
| 262 // Returns the trial name and selected group name for this field trial via | 262 // Returns the trial name and selected group name for this field trial via |
| 263 // the output parameter |field_trial_state|, but only if the trial has not | 263 // the output parameter |field_trial_state|, but only if the trial has not |
| 264 // been disabled. In that case, true is returned and |field_trial_state| is | 264 // been disabled. In that case, true is returned and |field_trial_state| is |
| 265 // filled in; otherwise, the result is false and |field_trial_state| is left | 265 // filled in; otherwise, the result is false and |field_trial_state| is left |
| 266 // untouched. | 266 // untouched. |
| 267 bool GetState(State* field_trial_state); | 267 bool GetState(State* field_trial_state); |
| 268 | 268 |
| 269 // Adds the field trial to the allocator whose memory is to be shared with | |
| 270 // child processes. Assumes the calling code has a lock around the call to | |
| 271 // this function, since the check for the allocator is not thread-safe. | |
| 272 void AddToAllocatorWhileLocked( | |
| 273 base::SharedPersistentMemoryAllocator* allocator); | |
| 274 | |
| 275 // Returns the group_name. A winner need not have been chosen. | 269 // Returns the group_name. A winner need not have been chosen. |
| 276 std::string group_name_internal() const { return group_name_; } | 270 std::string group_name_internal() const { return group_name_; } |
| 277 | 271 |
| 278 // The name of the field trial, as can be found via the FieldTrialList. | 272 // The name of the field trial, as can be found via the FieldTrialList. |
| 279 const std::string trial_name_; | 273 const std::string trial_name_; |
| 280 | 274 |
| 281 // The maximum sum of all probabilities supplied, which corresponds to 100%. | 275 // The maximum sum of all probabilities supplied, which corresponds to 100%. |
| 282 // This is the scaling factor used to adjust supplied probabilities. | 276 // This is the scaling factor used to adjust supplied probabilities. |
| 283 const Probability divisor_; | 277 const Probability divisor_; |
| 284 | 278 |
| (...skipping 27 matching lines...) Expand all Loading... |
| 312 // appropriate. | 306 // appropriate. |
| 313 bool forced_; | 307 bool forced_; |
| 314 | 308 |
| 315 // Specifies whether the group choice has been reported to observers. | 309 // Specifies whether the group choice has been reported to observers. |
| 316 bool group_reported_; | 310 bool group_reported_; |
| 317 | 311 |
| 318 // Whether this trial is registered with the global FieldTrialList and thus | 312 // Whether this trial is registered with the global FieldTrialList and thus |
| 319 // should notify it when its group is queried. | 313 // should notify it when its group is queried. |
| 320 bool trial_registered_; | 314 bool trial_registered_; |
| 321 | 315 |
| 316 // Reference to related field trial struct and data in shared memory. |
| 317 SharedPersistentMemoryAllocator::Reference ref_; |
| 318 |
| 322 // When benchmarking is enabled, field trials all revert to the 'default' | 319 // When benchmarking is enabled, field trials all revert to the 'default' |
| 323 // group. | 320 // group. |
| 324 static bool enable_benchmarking_; | 321 static bool enable_benchmarking_; |
| 325 | 322 |
| 326 DISALLOW_COPY_AND_ASSIGN(FieldTrial); | 323 DISALLOW_COPY_AND_ASSIGN(FieldTrial); |
| 327 }; | 324 }; |
| 328 | 325 |
| 329 //------------------------------------------------------------------------------ | 326 //------------------------------------------------------------------------------ |
| 330 // Class with a list of all active field trials. A trial is active if it has | 327 // Class with a list of all active field trials. A trial is active if it has |
| 331 // been registered, which includes evaluating its state based on its probaility. | 328 // been registered, which includes evaluating its state based on its probaility. |
| (...skipping 57 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 389 | 386 |
| 390 // Same as FactoryGetFieldTrial(), but allows specifying a custom seed to be | 387 // Same as FactoryGetFieldTrial(), but allows specifying a custom seed to be |
| 391 // used on one-time randomized field trials (instead of a hash of the trial | 388 // used on one-time randomized field trials (instead of a hash of the trial |
| 392 // name, which is used otherwise or if |randomization_seed| has value 0). The | 389 // name, which is used otherwise or if |randomization_seed| has value 0). The |
| 393 // |randomization_seed| value (other than 0) should never be the same for two | 390 // |randomization_seed| value (other than 0) should never be the same for two |
| 394 // trials, else this would result in correlated group assignments. Note: | 391 // trials, else this would result in correlated group assignments. Note: |
| 395 // Using a custom randomization seed is only supported by the | 392 // Using a custom randomization seed is only supported by the |
| 396 // PermutedEntropyProvider (which is used when UMA is not enabled). If | 393 // PermutedEntropyProvider (which is used when UMA is not enabled). If |
| 397 // |override_entropy_provider| is not null, then it will be used for | 394 // |override_entropy_provider| is not null, then it will be used for |
| 398 // randomization instead of the provider given when the FieldTrialList was | 395 // randomization instead of the provider given when the FieldTrialList was |
| 399 // instanciated. | 396 // instantiated. |
| 400 static FieldTrial* FactoryGetFieldTrialWithRandomizationSeed( | 397 static FieldTrial* FactoryGetFieldTrialWithRandomizationSeed( |
| 401 const std::string& trial_name, | 398 const std::string& trial_name, |
| 402 FieldTrial::Probability total_probability, | 399 FieldTrial::Probability total_probability, |
| 403 const std::string& default_group_name, | 400 const std::string& default_group_name, |
| 404 const int year, | 401 const int year, |
| 405 const int month, | 402 const int month, |
| 406 const int day_of_month, | 403 const int day_of_month, |
| 407 FieldTrial::RandomizationType randomization_type, | 404 FieldTrial::RandomizationType randomization_type, |
| 408 uint32_t randomization_seed, | 405 uint32_t randomization_seed, |
| 409 int* default_group_number, | 406 int* default_group_number, |
| (...skipping 103 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 513 const std::string& group_name); | 510 const std::string& group_name); |
| 514 | 511 |
| 515 // Add an observer to be notified when a field trial is irrevocably committed | 512 // Add an observer to be notified when a field trial is irrevocably committed |
| 516 // to being part of some specific field_group (and hence the group_name is | 513 // to being part of some specific field_group (and hence the group_name is |
| 517 // also finalized for that field_trial). | 514 // also finalized for that field_trial). |
| 518 static void AddObserver(Observer* observer); | 515 static void AddObserver(Observer* observer); |
| 519 | 516 |
| 520 // Remove an observer. | 517 // Remove an observer. |
| 521 static void RemoveObserver(Observer* observer); | 518 static void RemoveObserver(Observer* observer); |
| 522 | 519 |
| 520 // Grabs the lock and adds the field trial to the allocator. This should only |
| 521 // be called from FinalizeGroupChoice(). |
| 522 static void OnGroupFinalized(FieldTrial* field_trial); |
| 523 |
| 523 // Notify all observers that a group has been finalized for |field_trial|. | 524 // Notify all observers that a group has been finalized for |field_trial|. |
| 524 static void NotifyFieldTrialGroupSelection(FieldTrial* field_trial); | 525 static void NotifyFieldTrialGroupSelection(FieldTrial* field_trial); |
| 525 | 526 |
| 526 // Return the number of active field trials. | 527 // Return the number of active field trials. |
| 527 static size_t GetFieldTrialCount(); | 528 static size_t GetFieldTrialCount(); |
| 528 | 529 |
| 529 private: | 530 private: |
| 530 // Allow tests to access our innards for testing purposes. | 531 // Allow tests to access our innards for testing purposes. |
| 531 FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, InstantiateAllocator); | 532 FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, InstantiateAllocator); |
| 532 FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, AddTrialsToAllocator); | 533 FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, AddTrialsToAllocator); |
| 533 | 534 |
| 534 // Expects a mapped piece of shared memory |shm| that was created from the | 535 // Expects a mapped piece of shared memory |shm| that was created from the |
| 535 // browser process's field_trial_allocator and shared via the command line. | 536 // browser process's field_trial_allocator and shared via the command line. |
| 536 // This function recreates the allocator, iterates through all the field | 537 // This function recreates the allocator, iterates through all the field |
| 537 // trials in it, and creates them via CreateFieldTrial(). | 538 // trials in it, and creates them via CreateFieldTrial(). |
| 538 static void CreateTrialsFromSharedMemory( | 539 static void CreateTrialsFromSharedMemory( |
| 539 std::unique_ptr<base::SharedMemory> shm); | 540 std::unique_ptr<base::SharedMemory> shm); |
| 540 | 541 |
| 541 // Instantiate the field trial allocator, add all existing field trials to it, | 542 // Instantiate the field trial allocator, add all existing field trials to it, |
| 542 // and duplicates its handle to a read-only handle, which gets stored in | 543 // and duplicates its handle to a read-only handle, which gets stored in |
| 543 // |readonly_allocator_handle|. | 544 // |readonly_allocator_handle|. |
| 544 static void InstantiateFieldTrialAllocatorIfNeeded(); | 545 static void InstantiateFieldTrialAllocatorIfNeeded(); |
| 545 | 546 |
| 547 // Adds the field trial to the allocator. Caller must hold a lock before |
| 548 // calling this. |
| 549 static void AddToAllocatorWhileLocked(FieldTrial* field_trial); |
| 550 |
| 551 // Activate the corresponding field trial entry struct in shared memory. |
| 552 static void ActivateFieldTrialEntryWhileLocked(FieldTrial* field_trial); |
| 553 |
| 546 // A map from FieldTrial names to the actual instances. | 554 // A map from FieldTrial names to the actual instances. |
| 547 typedef std::map<std::string, FieldTrial*> RegistrationMap; | 555 typedef std::map<std::string, FieldTrial*> RegistrationMap; |
| 548 | 556 |
| 549 // If one-time randomization is enabled, returns a weak pointer to the | 557 // If one-time randomization is enabled, returns a weak pointer to the |
| 550 // corresponding EntropyProvider. Otherwise, returns NULL. | 558 // corresponding EntropyProvider. Otherwise, returns NULL. |
| 551 static const FieldTrial::EntropyProvider* | 559 static const FieldTrial::EntropyProvider* |
| 552 GetEntropyProviderForOneTimeRandomization(); | 560 GetEntropyProviderForOneTimeRandomization(); |
| 553 | 561 |
| 554 // Helper function should be called only while holding lock_. | 562 // Helper function should be called only while holding lock_. |
| 555 FieldTrial* PreLockedFind(const std::string& name); | 563 FieldTrial* PreLockedFind(const std::string& name); |
| (...skipping 20 matching lines...) Expand all Loading... |
| 576 // Entropy provider to be used for one-time randomized field trials. If NULL, | 584 // Entropy provider to be used for one-time randomized field trials. If NULL, |
| 577 // one-time randomization is not supported. | 585 // one-time randomization is not supported. |
| 578 std::unique_ptr<const FieldTrial::EntropyProvider> entropy_provider_; | 586 std::unique_ptr<const FieldTrial::EntropyProvider> entropy_provider_; |
| 579 | 587 |
| 580 // List of observers to be notified when a group is selected for a FieldTrial. | 588 // List of observers to be notified when a group is selected for a FieldTrial. |
| 581 scoped_refptr<ObserverListThreadSafe<Observer> > observer_list_; | 589 scoped_refptr<ObserverListThreadSafe<Observer> > observer_list_; |
| 582 | 590 |
| 583 // Allocator used to instantiate field trial in child processes. In the | 591 // Allocator used to instantiate field trial in child processes. In the |
| 584 // future, we may want to move this to a more generic place if we want to | 592 // future, we may want to move this to a more generic place if we want to |
| 585 // start passing more data other than field trials. | 593 // start passing more data other than field trials. |
| 586 std::unique_ptr<base::SharedPersistentMemoryAllocator> | 594 std::unique_ptr<SharedPersistentMemoryAllocator> field_trial_allocator_ = |
| 587 field_trial_allocator_ = nullptr; | 595 nullptr; |
| 588 | 596 |
| 589 #if defined(OS_WIN) | 597 #if defined(OS_WIN) |
| 590 // Readonly copy of the handle to the allocator. Needs to be a member variable | 598 // Readonly copy of the handle to the allocator. Needs to be a member variable |
| 591 // because it's needed from both CopyFieldTrialStateToFlags() and | 599 // because it's needed from both CopyFieldTrialStateToFlags() and |
| 592 // AppendFieldTrialHandleIfNeeded(). | 600 // AppendFieldTrialHandleIfNeeded(). |
| 593 HANDLE readonly_allocator_handle_ = nullptr; | 601 HANDLE readonly_allocator_handle_ = nullptr; |
| 594 #endif | 602 #endif |
| 595 | 603 |
| 596 DISALLOW_COPY_AND_ASSIGN(FieldTrialList); | 604 DISALLOW_COPY_AND_ASSIGN(FieldTrialList); |
| 597 }; | 605 }; |
| 598 | 606 |
| 599 } // namespace base | 607 } // namespace base |
| 600 | 608 |
| 601 #endif // BASE_METRICS_FIELD_TRIAL_H_ | 609 #endif // BASE_METRICS_FIELD_TRIAL_H_ |
| OLD | NEW |