forked from chromium/chromium
-
Notifications
You must be signed in to change notification settings - Fork 0
/
field_trial.h
821 lines (689 loc) · 38 KB
/
field_trial.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// FieldTrial is a class for handling details of statistical experiments
// performed by actual users in the field (i.e., in a shipped or beta product).
// All code is called exclusively on the UI thread currently.
//
// The simplest example is an experiment to see whether one of two options
// produces "better" results across our user population. In that scenario, UMA
// data is uploaded to aggregate the test results, and this FieldTrial class
// manages the state of each such experiment (state == which option was
// pseudo-randomly selected).
//
// States are typically generated randomly, either based on a one time
// randomization (which will yield the same results, in terms of selecting
// the client for a field trial or not, for every run of the program on a
// given machine), or by a session randomization (generated each time the
// application starts up, but held constant during the duration of the
// process).
//------------------------------------------------------------------------------
// Example: Suppose we have an experiment involving memory, such as determining
// the impact of some pruning algorithm.
// We assume that we already have a histogram of memory usage, such as:
// UMA_HISTOGRAM_COUNTS_1M("Memory.RendererTotal", count);
// Somewhere in main thread initialization code, we'd probably define an
// instance of a FieldTrial, with code such as:
// // FieldTrials are reference counted, and persist automagically until
// // process teardown, courtesy of their automatic registration in
// // FieldTrialList.
// // Note: This field trial will run in Chrome instances compiled through
// // 8 July, 2015, and after that all instances will be in "StandardMem".
// scoped_refptr<base::FieldTrial> trial(
// base::FieldTrialList::FactoryGetFieldTrial(
// "MemoryExperiment", 1000, "StandardMem", 2015, 7, 8,
// base::FieldTrial::ONE_TIME_RANDOMIZED, NULL));
//
// const int high_mem_group =
// trial->AppendGroup("HighMem", 20); // 2% in HighMem group.
// const int low_mem_group =
// trial->AppendGroup("LowMem", 20); // 2% in LowMem group.
// // Take action depending of which group we randomly land in.
// if (trial->group() == high_mem_group)
// SetPruningAlgorithm(kType1); // Sample setting of browser state.
// else if (trial->group() == low_mem_group)
// SetPruningAlgorithm(kType2); // Sample alternate setting.
//------------------------------------------------------------------------------
#ifndef BASE_METRICS_FIELD_TRIAL_H_
#define BASE_METRICS_FIELD_TRIAL_H_
#include <stddef.h>
#include <stdint.h>
#include <map>
#include <memory>
#include <set>
#include <string>
#include <vector>
#include "base/atomicops.h"
#include "base/base_export.h"
#include "base/command_line.h"
#include "base/feature_list.h"
#include "base/files/file.h"
#include "base/gtest_prod_util.h"
#include "base/macros.h"
#include "base/memory/read_only_shared_memory_region.h"
#include "base/memory/ref_counted.h"
#include "base/memory/shared_memory_mapping.h"
#include "base/metrics/persistent_memory_allocator.h"
#include "base/observer_list_threadsafe.h"
#include "base/pickle.h"
#include "base/process/launch.h"
#include "base/strings/string_piece.h"
#include "base/synchronization/lock.h"
#include "base/time/time.h"
#include "build/build_config.h"
#if defined(OS_MACOSX) && !defined(OS_IOS)
#include "base/mac/mach_port_rendezvous.h"
#endif
namespace base {
class FieldTrialList;
class BASE_EXPORT FieldTrial : public RefCounted<FieldTrial> {
public:
typedef int Probability; // Probability type for being selected in a trial.
// Specifies the persistence of the field trial group choice.
enum RandomizationType {
// One time randomized trials will persist the group choice between
// restarts, which is recommended for most trials, especially those that
// change user visible behavior.
ONE_TIME_RANDOMIZED,
// Session randomized trials will roll the dice to select a group on every
// process restart.
SESSION_RANDOMIZED,
};
// EntropyProvider is an interface for providing entropy for one-time
// randomized (persistent) field trials.
class BASE_EXPORT EntropyProvider {
public:
virtual ~EntropyProvider();
// Returns a double in the range of [0, 1) to be used for the dice roll for
// the specified field trial. If |randomization_seed| is not 0, it will be
// used in preference to |trial_name| for generating the entropy by entropy
// providers that support it. A given instance should always return the same
// value given the same input |trial_name| and |randomization_seed| values.
virtual double GetEntropyForTrial(const std::string& trial_name,
uint32_t randomization_seed) const = 0;
};
// A pair representing a Field Trial and its selected group.
struct ActiveGroup {
std::string trial_name;
std::string group_name;
};
// A triplet representing a FieldTrial, its selected group and whether it's
// active. String members are pointers to the underlying strings owned by the
// FieldTrial object. Does not use StringPiece to avoid conversions back to
// std::string.
struct BASE_EXPORT State {
const std::string* trial_name = nullptr;
const std::string* group_name = nullptr;
bool activated = false;
State();
State(const State& other);
~State();
};
// We create one FieldTrialEntry per field trial in shared memory, via
// AddToAllocatorWhileLocked. The FieldTrialEntry is followed by a
// base::Pickle object that we unpickle and read from.
struct BASE_EXPORT FieldTrialEntry {
// SHA1(FieldTrialEntry): Increment this if structure changes!
static constexpr uint32_t kPersistentTypeId = 0xABA17E13 + 2;
// Expected size for 32/64-bit check.
static constexpr size_t kExpectedInstanceSize = 8;
// Whether or not this field trial is activated. This is really just a
// boolean but using a 32 bit value for portability reasons. It should be
// accessed via NoBarrier_Load()/NoBarrier_Store() to prevent the compiler
// from doing unexpected optimizations because it thinks that only one
// thread is accessing the memory location.
subtle::Atomic32 activated;
// Size of the pickled structure, NOT the total size of this entry.
uint32_t pickle_size;
// Calling this is only valid when the entry is initialized. That is, it
// resides in shared memory and has a pickle containing the trial name and
// group name following it.
bool GetTrialAndGroupName(StringPiece* trial_name,
StringPiece* group_name) const;
// Calling this is only valid when the entry is initialized as well. Reads
// the parameters following the trial and group name and stores them as
// key-value mappings in |params|.
bool GetParams(std::map<std::string, std::string>* params) const;
private:
// Returns an iterator over the data containing names and params.
PickleIterator GetPickleIterator() const;
// Takes the iterator and writes out the first two items into |trial_name|
// and |group_name|.
bool ReadStringPair(PickleIterator* iter,
StringPiece* trial_name,
StringPiece* group_name) const;
};
typedef std::vector<ActiveGroup> ActiveGroups;
// A return value to indicate that a given instance has not yet had a group
// assignment (and hence is not yet participating in the trial).
static const int kNotFinalized;
// Disables this trial, meaning it always determines the default group
// has been selected. May be called immediately after construction, or
// at any time after initialization (should not be interleaved with
// AppendGroup calls). Once disabled, there is no way to re-enable a
// trial.
// TODO(mad): http://code.google.com/p/chromium/issues/detail?id=121446
// This doesn't properly reset to Default when a group was forced.
void Disable();
// Establish the name and probability of the next group in this trial.
// Sometimes, based on construction randomization, this call may cause the
// provided group to be *THE* group selected for use in this instance.
// The return value is the group number of the new group.
int AppendGroup(const std::string& name, Probability group_probability);
// Return the name of the FieldTrial (excluding the group name).
const std::string& trial_name() const { return trial_name_; }
// Return the randomly selected group number that was assigned, and notify
// any/all observers that this finalized group number has presumably been used
// (queried), and will never change. Note that this will force an instance to
// participate, and make it illegal to attempt to probabilistically add any
// other groups to the trial.
int group();
// If the group's name is empty, a string version containing the group number
// is used as the group name. This causes a winner to be chosen if none was.
const std::string& group_name();
// Finalizes the group choice and returns the chosen group, but does not mark
// the trial as active - so its state will not be reported until group_name()
// or similar is called.
const std::string& GetGroupNameWithoutActivation();
// Set the field trial as forced, meaning that it was setup earlier than
// the hard coded registration of the field trial to override it.
// This allows the code that was hard coded to register the field trial to
// still succeed even though the field trial has already been registered.
// This must be called after appending all the groups, since we will make
// the group choice here. Note that this is a NOOP for already forced trials.
// And, as the rest of the FieldTrial code, this is not thread safe and must
// be done from the UI thread.
void SetForced();
// Enable benchmarking sets field trials to a common setting.
static void EnableBenchmarking();
// Creates a FieldTrial object with the specified parameters, to be used for
// simulation of group assignment without actually affecting global field
// trial state in the running process. Group assignment will be done based on
// |entropy_value|, which must have a range of [0, 1).
//
// Note: Using this function will not register the field trial globally in the
// running process - for that, use FieldTrialList::FactoryGetFieldTrial().
//
// The ownership of the returned FieldTrial is transfered to the caller which
// is responsible for deref'ing it (e.g. by using scoped_refptr<FieldTrial>).
static FieldTrial* CreateSimulatedFieldTrial(
const std::string& trial_name,
Probability total_probability,
const std::string& default_group_name,
double entropy_value);
private:
// Allow tests to access our innards for testing purposes.
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Registration);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, AbsoluteProbabilities);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, RemainingProbability);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, FiftyFiftyProbability);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MiddleProbabilities);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, OneWinner);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DisableProbability);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, ActiveGroups);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, AllGroups);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, ActiveGroupsNotFinalized);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Save);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SaveAll);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DuplicateRestore);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedTurnFeatureOff);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedTurnFeatureOn);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedChangeDefault_Default);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedChangeDefault_NonDefault);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, FloatBoundariesGiveEqualGroupSizes);
FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DoesNotSurpassTotalProbability);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest,
DoNotAddSimulatedFieldTrialsToAllocator);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, ClearParamsFromSharedMemory);
friend class base::FieldTrialList;
friend class RefCounted<FieldTrial>;
using FieldTrialRef = PersistentMemoryAllocator::Reference;
// This is the group number of the 'default' group when a choice wasn't forced
// by a call to FieldTrialList::CreateFieldTrial. It is kept private so that
// consumers don't use it by mistake in cases where the group was forced.
static const int kDefaultGroupNumber;
// Creates a field trial with the specified parameters. Group assignment will
// be done based on |entropy_value|, which must have a range of [0, 1).
FieldTrial(const std::string& trial_name,
Probability total_probability,
const std::string& default_group_name,
double entropy_value);
virtual ~FieldTrial();
// Return the default group name of the FieldTrial.
std::string default_group_name() const { return default_group_name_; }
// Marks this trial as having been registered with the FieldTrialList. Must be
// called no more than once and before any |group()| calls have occurred.
void SetTrialRegistered();
// Sets the chosen group name and number.
void SetGroupChoice(const std::string& group_name, int number);
// Ensures that a group is chosen, if it hasn't yet been. The field trial
// might yet be disabled, so this call will *not* notify observers of the
// status.
void FinalizeGroupChoice();
// Implements FinalizeGroupChoice() with the added flexibility of being
// deadlock-free if |is_locked| is true and the caller is holding a lock.
void FinalizeGroupChoiceImpl(bool is_locked);
// Returns the trial name and selected group name for this field trial via
// the output parameter |active_group|, but only if the group has already
// been chosen and has been externally observed via |group()| and the trial
// has not been disabled. In that case, true is returned and |active_group|
// is filled in; otherwise, the result is false and |active_group| is left
// untouched.
bool GetActiveGroup(ActiveGroup* active_group) const;
// Returns the trial name and selected group name for this field trial via
// the output parameter |field_trial_state| for all the studies when
// |bool include_expired| is true. In case when |bool include_expired| is
// false, if the trial has not been disabled true is returned and
// |field_trial_state| is filled in; otherwise, the result is false and
// |field_trial_state| is left untouched.
// This function is deadlock-free if the caller is holding a lock.
bool GetStateWhileLocked(State* field_trial_state, bool include_expired);
// Returns the group_name. A winner need not have been chosen.
std::string group_name_internal() const { return group_name_; }
// The name of the field trial, as can be found via the FieldTrialList.
const std::string trial_name_;
// The maximum sum of all probabilities supplied, which corresponds to 100%.
// This is the scaling factor used to adjust supplied probabilities.
const Probability divisor_;
// The name of the default group.
const std::string default_group_name_;
// The randomly selected probability that is used to select a group (or have
// the instance not participate). It is the product of divisor_ and a random
// number between [0, 1).
Probability random_;
// Sum of the probabilities of all appended groups.
Probability accumulated_group_probability_;
// The number that will be returned by the next AppendGroup() call.
int next_group_number_;
// The pseudo-randomly assigned group number.
// This is kNotFinalized if no group has been assigned.
int group_;
// A textual name for the randomly selected group. Valid after |group()|
// has been called.
std::string group_name_;
// When enable_field_trial_ is false, field trial reverts to the 'default'
// group.
bool enable_field_trial_;
// When forced_ is true, we return the chosen group from AppendGroup when
// appropriate.
bool forced_;
// Specifies whether the group choice has been reported to observers.
bool group_reported_;
// Whether this trial is registered with the global FieldTrialList and thus
// should notify it when its group is queried.
bool trial_registered_;
// Reference to related field trial struct and data in shared memory.
FieldTrialRef ref_;
// When benchmarking is enabled, field trials all revert to the 'default'
// group.
static bool enable_benchmarking_;
DISALLOW_COPY_AND_ASSIGN(FieldTrial);
};
//------------------------------------------------------------------------------
// Class with a list of all active field trials. A trial is active if it has
// been registered, which includes evaluating its state based on its probaility.
// Only one instance of this class exists and outside of testing, will live for
// the entire life time of the process.
class BASE_EXPORT FieldTrialList {
public:
using FieldTrialAllocator = PersistentMemoryAllocator;
// Type for function pointer passed to |AllParamsToString| used to escape
// special characters from |input|.
typedef std::string (*EscapeDataFunc)(const std::string& input);
// Year that is guaranteed to not be expired when instantiating a field trial
// via |FactoryGetFieldTrial()|. Set to two years from the build date.
static int kNoExpirationYear;
// Observer is notified when a FieldTrial's group is selected.
class BASE_EXPORT Observer {
public:
// Notify observers when FieldTrials's group is selected.
virtual void OnFieldTrialGroupFinalized(const std::string& trial_name,
const std::string& group_name) = 0;
protected:
virtual ~Observer();
};
// This singleton holds the global list of registered FieldTrials.
//
// To support one-time randomized field trials, specify a non-null
// |entropy_provider| which should be a source of uniformly distributed
// entropy values. If one time randomization is not desired, pass in null for
// |entropy_provider|.
explicit FieldTrialList(
std::unique_ptr<const FieldTrial::EntropyProvider> entropy_provider);
// Destructor Release()'s references to all registered FieldTrial instances.
~FieldTrialList();
// Get a FieldTrial instance from the factory.
//
// |name| is used to register the instance with the FieldTrialList class,
// and can be used to find the trial (only one trial can be present for each
// name). |default_group_name| is the name of the default group which will
// be chosen if none of the subsequent appended groups get to be chosen.
// |default_group_number| can receive the group number of the default group as
// AppendGroup returns the number of the subsequence groups. |trial_name| and
// |default_group_name| may not be empty but |default_group_number| can be
// NULL if the value is not needed.
//
// Group probabilities that are later supplied must sum to less than or equal
// to the |total_probability|. Arguments |year|, |month| and |day_of_month|
// specify the expiration time. If the build time is after the expiration time
// then the field trial reverts to the 'default' group.
//
// Use this static method to get a startup-randomized FieldTrial or a
// previously created forced FieldTrial.
static FieldTrial* FactoryGetFieldTrial(
const std::string& trial_name,
FieldTrial::Probability total_probability,
const std::string& default_group_name,
const int year,
const int month,
const int day_of_month,
FieldTrial::RandomizationType randomization_type,
int* default_group_number);
// Same as FactoryGetFieldTrial(), but allows specifying a custom seed to be
// used on one-time randomized field trials (instead of a hash of the trial
// name, which is used otherwise or if |randomization_seed| has value 0). The
// |randomization_seed| value (other than 0) should never be the same for two
// trials, else this would result in correlated group assignments. Note:
// Using a custom randomization seed is only supported by the
// NormalizedMurmurHashEntropyProvider, which is used when UMA is not enabled
// (and is always used in Android WebView, where UMA is enabled
// asyncronously). If |override_entropy_provider| is not null, then it will be
// used for randomization instead of the provider given when the
// FieldTrialList was instantiated.
static FieldTrial* FactoryGetFieldTrialWithRandomizationSeed(
const std::string& trial_name,
FieldTrial::Probability total_probability,
const std::string& default_group_name,
const int year,
const int month,
const int day_of_month,
FieldTrial::RandomizationType randomization_type,
uint32_t randomization_seed,
int* default_group_number,
const FieldTrial::EntropyProvider* override_entropy_provider);
// The Find() method can be used to test to see if a named trial was already
// registered, or to retrieve a pointer to it from the global map.
static FieldTrial* Find(const std::string& trial_name);
// Returns the group number chosen for the named trial, or
// FieldTrial::kNotFinalized if the trial does not exist.
static int FindValue(const std::string& trial_name);
// Returns the group name chosen for the named trial, or the empty string if
// the trial does not exist. The first call of this function on a given field
// trial will mark it as active, so that its state will be reported with usage
// metrics, crashes, etc.
// Note: Direct use of this function and related FieldTrial functions is
// generally discouraged - instead please use base::Feature when possible.
static std::string FindFullName(const std::string& trial_name);
// Returns true if the named trial has been registered.
static bool TrialExists(const std::string& trial_name);
// Returns true if the named trial exists and has been activated.
static bool IsTrialActive(const std::string& trial_name);
// Creates a persistent representation of active FieldTrial instances for
// resurrection in another process. This allows randomization to be done in
// one process, and secondary processes can be synchronized on the result.
// The resulting string contains the name and group name pairs of all
// registered FieldTrials for which the group has been chosen and externally
// observed (via |group()|) and which have not been disabled, with "/" used
// to separate all names and to terminate the string. This string is parsed
// by |CreateTrialsFromString()|.
static void StatesToString(std::string* output);
// Creates a persistent representation of all FieldTrial instances for
// resurrection in another process. This allows randomization to be done in
// one process, and secondary processes can be synchronized on the result.
// The resulting string contains the name and group name pairs of all
// registered FieldTrials including disabled based on |include_expired|,
// with "/" used to separate all names and to terminate the string. All
// activated trials have their name prefixed with "*". This string is parsed
// by |CreateTrialsFromString()|.
static void AllStatesToString(std::string* output, bool include_expired);
// Creates a persistent representation of all FieldTrial params for
// resurrection in another process. The returned string contains the trial
// name and group name pairs of all registered FieldTrials including disabled
// based on |include_expired| separated by '.'. The pair is followed by ':'
// separator and list of param name and values separated by '/'. It also takes
// |encode_data_func| function pointer for encodeing special charactors.
// This string is parsed by |AssociateParamsFromString()|.
static std::string AllParamsToString(bool include_expired,
EscapeDataFunc encode_data_func);
// Fills in the supplied vector |active_groups| (which must be empty when
// called) with a snapshot of all registered FieldTrials for which the group
// has been chosen and externally observed (via |group()|) and which have
// not been disabled.
static void GetActiveFieldTrialGroups(
FieldTrial::ActiveGroups* active_groups);
// Returns the field trials that are marked active in |trials_string|.
static void GetActiveFieldTrialGroupsFromString(
const std::string& trials_string,
FieldTrial::ActiveGroups* active_groups);
// Returns the field trials that were active when the process was
// created. Either parses the field trial string or the shared memory
// holding field trial information.
// Must be called only after a call to CreateTrialsFromCommandLine().
static void GetInitiallyActiveFieldTrials(
const base::CommandLine& command_line,
FieldTrial::ActiveGroups* active_groups);
// Use a state string (re: StatesToString()) to augment the current list of
// field trials to include the supplied trials, and using a 100% probability
// for each trial, force them to have the same group string. This is commonly
// used in a non-browser process, to carry randomly selected state in a
// browser process into this non-browser process, but could also be invoked
// through a command line argument to the browser process. Created field
// trials will be marked "used" for the purposes of active trial reporting
// if they are prefixed with |kActivationMarker|. Trial names in
// |ignored_trial_names| are ignored when parsing |trials_string|.
static bool CreateTrialsFromString(
const std::string& trials_string,
const std::set<std::string>& ignored_trial_names);
// Achieves the same thing as CreateTrialsFromString, except wraps the logic
// by taking in the trials from the command line, either via shared memory
// handle or command line argument. A bit of a misnomer since on POSIX we
// simply get the trials from opening |fd_key| if using shared memory. On
// Windows, we expect the |cmd_line| switch for |field_trial_handle_switch| to
// contain the shared memory handle that contains the field trial allocator.
// We need the |field_trial_handle_switch| and |fd_key| arguments to be passed
// in since base/ can't depend on content/.
static void CreateTrialsFromCommandLine(const base::CommandLine& cmd_line,
const char* field_trial_handle_switch,
int fd_key);
// Creates base::Feature overrides from the command line by first trying to
// use shared memory and then falling back to the command line if it fails.
static void CreateFeaturesFromCommandLine(
const base::CommandLine& command_line,
const char* enable_features_switch,
const char* disable_features_switch,
FeatureList* feature_list);
#if defined(OS_WIN)
// On Windows, we need to explicitly pass down any handles to be inherited.
// This function adds the shared memory handle to field trial state to the
// list of handles to be inherited.
static void AppendFieldTrialHandleIfNeeded(
base::HandlesToInheritVector* handles);
#elif defined(OS_FUCHSIA)
// TODO(fuchsia): Implement shared-memory configuration (crbug.com/752368).
#elif defined(OS_MACOSX) && !defined(OS_IOS)
// On Mac, the field trial shared memory is accessed via a Mach server, which
// the child looks up directly.
static void InsertFieldTrialHandleIfNeeded(
MachPortsForRendezvous* rendezvous_ports);
#elif defined(OS_POSIX) && !defined(OS_NACL)
// On POSIX, we also need to explicitly pass down this file descriptor that
// should be shared with the child process. Returns -1 if it was not
// initialized properly. The current process remains the onwer of the passed
// descriptor.
static int GetFieldTrialDescriptor();
#endif
static base::ReadOnlySharedMemoryRegion
DuplicateFieldTrialSharedMemoryForTesting();
// Adds a switch to the command line containing the field trial state as a
// string (if not using shared memory to share field trial state), or the
// shared memory handle + length.
// Needs the |field_trial_handle_switch| argument to be passed in since base/
// can't depend on content/.
static void CopyFieldTrialStateToFlags(const char* field_trial_handle_switch,
const char* enable_features_switch,
const char* disable_features_switch,
base::CommandLine* cmd_line);
// Create a FieldTrial with the given |name| and using 100% probability for
// the FieldTrial, force FieldTrial to have the same group string as
// |group_name|. This is commonly used in a non-browser process, to carry
// randomly selected state in a browser process into this non-browser process.
// It returns NULL if there is a FieldTrial that is already registered with
// the same |name| but has different finalized group string (|group_name|).
static FieldTrial* CreateFieldTrial(const std::string& name,
const std::string& group_name);
// Add an observer to be notified when a field trial is irrevocably committed
// to being part of some specific field_group (and hence the group_name is
// also finalized for that field_trial). Returns false and does nothing if
// there is no FieldTrialList singleton.
static bool AddObserver(Observer* observer);
// Remove an observer.
static void RemoveObserver(Observer* observer);
// Similar to AddObserver(), but the passed observer will be notified
// synchronously when a field trial is activated and its group selected. It
// will be notified synchronously on the same thread where the activation and
// group selection happened. It is the responsibility of the observer to make
// sure that this is a safe operation and the operation must be fast, as this
// work is done synchronously as part of group() or related APIs. Only a
// single such observer is supported, exposed specifically for crash
// reporting. Must be called on the main thread before any other threads
// have been started.
static void SetSynchronousObserver(Observer* observer);
// Removes the single synchronous observer.
static void RemoveSynchronousObserver(Observer* observer);
// Grabs the lock if necessary and adds the field trial to the allocator. This
// should only be called from FinalizeGroupChoice().
static void OnGroupFinalized(bool is_locked, FieldTrial* field_trial);
// Notify all observers that a group has been finalized for |field_trial|.
static void NotifyFieldTrialGroupSelection(FieldTrial* field_trial);
// Return the number of active field trials.
static size_t GetFieldTrialCount();
// Gets the parameters for |field_trial| from shared memory and stores them in
// |params|. This is only exposed for use by FieldTrialParamAssociator and
// shouldn't be used by anything else.
static bool GetParamsFromSharedMemory(
FieldTrial* field_trial,
std::map<std::string, std::string>* params);
// Clears all the params in the allocator.
static void ClearParamsFromSharedMemoryForTesting();
// Dumps field trial state to an allocator so that it can be analyzed after a
// crash.
static void DumpAllFieldTrialsToPersistentAllocator(
PersistentMemoryAllocator* allocator);
// Retrieves field trial state from an allocator so that it can be analyzed
// after a crash. The pointers in the returned vector are into the persistent
// memory segment and so are only valid as long as the allocator is valid.
static std::vector<const FieldTrial::FieldTrialEntry*>
GetAllFieldTrialsFromPersistentAllocator(
PersistentMemoryAllocator const& allocator);
// Returns true if a global field trial list is set. Only used for testing.
static bool IsGlobalSetForTesting();
private:
// Allow tests to access our innards for testing purposes.
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, InstantiateAllocator);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, AddTrialsToAllocator);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest,
DoNotAddSimulatedFieldTrialsToAllocator);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, AssociateFieldTrialParams);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, ClearParamsFromSharedMemory);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest,
SerializeSharedMemoryRegionMetadata);
friend int SerializeSharedMemoryRegionMetadata(void);
FRIEND_TEST_ALL_PREFIXES(FieldTrialListTest, CheckReadOnlySharedMemoryRegion);
// Serialization is used to pass information about the handle to child
// processes. It passes a reference to the relevant OS resource, and it passes
// a GUID. Serialization and deserialization doesn't actually transport the
// underlying OS resource - that must be done by the Process launcher.
static std::string SerializeSharedMemoryRegionMetadata(
const base::ReadOnlySharedMemoryRegion& shm);
#if defined(OS_WIN) || defined(OS_FUCHSIA) || \
(defined(OS_MACOSX) && !defined(OS_IOS))
static base::ReadOnlySharedMemoryRegion DeserializeSharedMemoryRegionMetadata(
const std::string& switch_value);
#elif defined(OS_POSIX) && !defined(OS_NACL)
static base::ReadOnlySharedMemoryRegion DeserializeSharedMemoryRegionMetadata(
int fd,
const std::string& switch_value);
#endif
#if defined(OS_WIN) || defined(OS_FUCHSIA) || \
(defined(OS_MACOSX) && !defined(OS_IOS))
// Takes in |handle_switch| from the command line which represents the shared
// memory handle for field trials, parses it, and creates the field trials.
// Returns true on success, false on failure.
// |switch_value| also contains the serialized GUID.
static bool CreateTrialsFromSwitchValue(const std::string& switch_value);
#elif defined(OS_POSIX) && !defined(OS_NACL)
// On POSIX systems that use the zygote, we look up the correct fd that backs
// the shared memory segment containing the field trials by looking it up via
// an fd key in GlobalDescriptors. Returns true on success, false on failure.
// |switch_value| also contains the serialized GUID.
static bool CreateTrialsFromDescriptor(int fd_key,
const std::string& switch_value);
#endif
// Takes an unmapped ReadOnlySharedMemoryRegion, maps it with the correct size
// and creates field trials via CreateTrialsFromSharedMemoryMapping(). Returns
// true if successful and false otherwise.
static bool CreateTrialsFromSharedMemoryRegion(
const base::ReadOnlySharedMemoryRegion& shm_region);
// Expects a mapped piece of shared memory |shm_mapping| that was created from
// the browser process's field_trial_allocator and shared via the command
// line. This function recreates the allocator, iterates through all the field
// trials in it, and creates them via CreateFieldTrial(). Returns true if
// successful and false otherwise.
static bool CreateTrialsFromSharedMemoryMapping(
base::ReadOnlySharedMemoryMapping shm_mapping);
// Instantiate the field trial allocator, add all existing field trials to it,
// and duplicates its handle to a read-only handle, which gets stored in
// |readonly_allocator_handle|.
static void InstantiateFieldTrialAllocatorIfNeeded();
// Adds the field trial to the allocator. Caller must hold a lock before
// calling this.
static void AddToAllocatorWhileLocked(PersistentMemoryAllocator* allocator,
FieldTrial* field_trial);
// Activate the corresponding field trial entry struct in shared memory.
static void ActivateFieldTrialEntryWhileLocked(FieldTrial* field_trial);
// A map from FieldTrial names to the actual instances.
typedef std::map<std::string, FieldTrial*> RegistrationMap;
// If one-time randomization is enabled, returns a weak pointer to the
// corresponding EntropyProvider. Otherwise, returns NULL.
static const FieldTrial::EntropyProvider*
GetEntropyProviderForOneTimeRandomization();
// Helper function should be called only while holding lock_.
FieldTrial* PreLockedFind(const std::string& name);
// Register() stores a pointer to the given trial in a global map.
// This method also AddRef's the indicated trial.
// This should always be called after creating a new FieldTrial instance.
static void Register(FieldTrial* trial);
// Returns all the registered trials.
static RegistrationMap GetRegisteredTrials();
static FieldTrialList* global_; // The singleton of this class.
// This will tell us if there is an attempt to register a field
// trial or check if one-time randomization is enabled without
// creating the FieldTrialList. This is not an error, unless a
// FieldTrialList is created after that.
static bool used_without_global_;
// Lock for access to registered_ and field_trial_allocator_.
Lock lock_;
RegistrationMap registered_;
std::map<std::string, std::string> seen_states_;
// Entropy provider to be used for one-time randomized field trials. If NULL,
// one-time randomization is not supported.
std::unique_ptr<const FieldTrial::EntropyProvider> entropy_provider_;
// List of observers to be notified when a group is selected for a FieldTrial.
scoped_refptr<ObserverListThreadSafe<Observer> > observer_list_;
// Single synchronous observer to be notified when a trial group is chosen.
Observer* synchronous_observer_ = nullptr;
// Allocator in shared memory containing field trial data. Used in both
// browser and child processes, but readonly in the child.
// In the future, we may want to move this to a more generic place if we want
// to start passing more data other than field trials.
std::unique_ptr<FieldTrialAllocator> field_trial_allocator_ = nullptr;
// Readonly copy of the region to the allocator. Needs to be a member variable
// because it's needed from both CopyFieldTrialStateToFlags() and
// AppendFieldTrialHandleIfNeeded().
base::ReadOnlySharedMemoryRegion readonly_allocator_region_;
// Tracks whether CreateTrialsFromCommandLine() has been called.
bool create_trials_from_command_line_called_ = false;
DISALLOW_COPY_AND_ASSIGN(FieldTrialList);
};
} // namespace base
#endif // BASE_METRICS_FIELD_TRIAL_H_