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 #include "base/metrics/field_trial.h" 6 7 #include <algorithm> 8 9 #include "base/build_time.h" 10 #include "base/logging.h" 11 #include "base/rand_util.h" 12 #include "base/strings/string_number_conversions.h" 13 #include "base/strings/string_util.h" 14 #include "base/strings/stringprintf.h" 15 #include "base/strings/utf_string_conversions.h" 16 17 namespace base { 18 19 namespace { 20 21 // Define a separator character to use when creating a persistent form of an 22 // instance. This is intended for use as a command line argument, passed to a 23 // second process to mimic our state (i.e., provide the same group name). 24 const char kPersistentStringSeparator = '/'; // Currently a slash. 25 26 // Define a marker character to be used as a prefix to a trial name on the 27 // command line which forces its activation. 28 const char kActivationMarker = '*'; 29 30 // Created a time value based on |year|, |month| and |day_of_month| parameters. 31 Time CreateTimeFromParams(int year, int month, int day_of_month) { 32 DCHECK_GT(year, 1970); 33 DCHECK_GT(month, 0); 34 DCHECK_LT(month, 13); 35 DCHECK_GT(day_of_month, 0); 36 DCHECK_LT(day_of_month, 32); 37 38 Time::Exploded exploded; 39 exploded.year = year; 40 exploded.month = month; 41 exploded.day_of_week = 0; // Should be unused. 42 exploded.day_of_month = day_of_month; 43 exploded.hour = 0; 44 exploded.minute = 0; 45 exploded.second = 0; 46 exploded.millisecond = 0; 47 Time out_time; 48 if (!Time::FromLocalExploded(exploded, &out_time)) { 49 // TODO(maksims): implement failure handling. 50 // We might just return |out_time|, which is Time(0). 51 NOTIMPLEMENTED(); 52 } 53 54 return out_time; 55 } 56 57 // Returns the boundary value for comparing against the FieldTrial's added 58 // groups for a given |divisor| (total probability) and |entropy_value|. 59 FieldTrial::Probability GetGroupBoundaryValue( 60 FieldTrial::Probability divisor, 61 double entropy_value) { 62 // Add a tiny epsilon value to get consistent results when converting floating 63 // points to int. Without it, boundary values have inconsistent results, e.g.: 64 // 65 // static_cast<FieldTrial::Probability>(100 * 0.56) == 56 66 // static_cast<FieldTrial::Probability>(100 * 0.57) == 56 67 // static_cast<FieldTrial::Probability>(100 * 0.58) == 57 68 // static_cast<FieldTrial::Probability>(100 * 0.59) == 59 69 const double kEpsilon = 1e-8; 70 const FieldTrial::Probability result = 71 static_cast<FieldTrial::Probability>(divisor * entropy_value + kEpsilon); 72 // Ensure that adding the epsilon still results in a value < |divisor|. 73 return std::min(result, divisor - 1); 74 } 75 76 // Parses the --force-fieldtrials string |trials_string| into |entries|. 77 // Returns true if the string was parsed correctly. On failure, the |entries| 78 // array may end up being partially filled. 79 bool ParseFieldTrialsString(const std::string& trials_string, 80 std::vector<FieldTrial::State>* entries) { 81 const StringPiece trials_string_piece(trials_string); 82 83 size_t next_item = 0; 84 while (next_item < trials_string.length()) { 85 size_t name_end = trials_string.find(kPersistentStringSeparator, next_item); 86 if (name_end == trials_string.npos || next_item == name_end) 87 return false; 88 size_t group_name_end = 89 trials_string.find(kPersistentStringSeparator, name_end + 1); 90 if (name_end + 1 == group_name_end) 91 return false; 92 if (group_name_end == trials_string.npos) 93 group_name_end = trials_string.length(); 94 95 FieldTrial::State entry; 96 // Verify if the trial should be activated or not. 97 if (trials_string[next_item] == kActivationMarker) { 98 // Name cannot be only the indicator. 99 if (name_end - next_item == 1) 100 return false; 101 next_item++; 102 entry.activated = true; 103 } 104 entry.trial_name = 105 trials_string_piece.substr(next_item, name_end - next_item); 106 entry.group_name = 107 trials_string_piece.substr(name_end + 1, group_name_end - name_end - 1); 108 next_item = group_name_end + 1; 109 110 entries->push_back(entry); 111 } 112 return true; 113 } 114 115 } // namespace 116 117 // statics 118 const int FieldTrial::kNotFinalized = -1; 119 const int FieldTrial::kDefaultGroupNumber = 0; 120 bool FieldTrial::enable_benchmarking_ = false; 121 122 int FieldTrialList::kNoExpirationYear = 0; 123 124 //------------------------------------------------------------------------------ 125 // FieldTrial methods and members. 126 127 FieldTrial::EntropyProvider::~EntropyProvider() { 128 } 129 130 FieldTrial::State::State() : activated(false) {} 131 132 FieldTrial::State::State(const State& other) = default; 133 134 FieldTrial::State::~State() {} 135 136 void FieldTrial::Disable() { 137 DCHECK(!group_reported_); 138 enable_field_trial_ = false; 139 140 // In case we are disabled after initialization, we need to switch 141 // the trial to the default group. 142 if (group_ != kNotFinalized) { 143 // Only reset when not already the default group, because in case we were 144 // forced to the default group, the group number may not be 145 // kDefaultGroupNumber, so we should keep it as is. 146 if (group_name_ != default_group_name_) 147 SetGroupChoice(default_group_name_, kDefaultGroupNumber); 148 } 149 } 150 151 int FieldTrial::AppendGroup(const std::string& name, 152 Probability group_probability) { 153 // When the group choice was previously forced, we only need to return the 154 // the id of the chosen group, and anything can be returned for the others. 155 if (forced_) { 156 DCHECK(!group_name_.empty()); 157 if (name == group_name_) { 158 // Note that while |group_| may be equal to |kDefaultGroupNumber| on the 159 // forced trial, it will not have the same value as the default group 160 // number returned from the non-forced |FactoryGetFieldTrial()| call, 161 // which takes care to ensure that this does not happen. 162 return group_; 163 } 164 DCHECK_NE(next_group_number_, group_); 165 // We still return different numbers each time, in case some caller need 166 // them to be different. 167 return next_group_number_++; 168 } 169 170 DCHECK_LE(group_probability, divisor_); 171 DCHECK_GE(group_probability, 0); 172 173 if (enable_benchmarking_ || !enable_field_trial_) 174 group_probability = 0; 175 176 accumulated_group_probability_ += group_probability; 177 178 DCHECK_LE(accumulated_group_probability_, divisor_); 179 if (group_ == kNotFinalized && accumulated_group_probability_ > random_) { 180 // This is the group that crossed the random line, so we do the assignment. 181 SetGroupChoice(name, next_group_number_); 182 } 183 return next_group_number_++; 184 } 185 186 int FieldTrial::group() { 187 FinalizeGroupChoice(); 188 if (trial_registered_) 189 FieldTrialList::NotifyFieldTrialGroupSelection(this); 190 return group_; 191 } 192 193 const std::string& FieldTrial::group_name() { 194 // Call |group()| to ensure group gets assigned and observers are notified. 195 group(); 196 DCHECK(!group_name_.empty()); 197 return group_name_; 198 } 199 200 const std::string& FieldTrial::GetGroupNameWithoutActivation() { 201 FinalizeGroupChoice(); 202 return group_name_; 203 } 204 205 void FieldTrial::SetForced() { 206 // We might have been forced before (e.g., by CreateFieldTrial) and it's 207 // first come first served, e.g., command line switch has precedence. 208 if (forced_) 209 return; 210 211 // And we must finalize the group choice before we mark ourselves as forced. 212 FinalizeGroupChoice(); 213 forced_ = true; 214 } 215 216 // static 217 void FieldTrial::EnableBenchmarking() { 218 DCHECK_EQ(0u, FieldTrialList::GetFieldTrialCount()); 219 enable_benchmarking_ = true; 220 } 221 222 // static 223 FieldTrial* FieldTrial::CreateSimulatedFieldTrial( 224 const std::string& trial_name, 225 Probability total_probability, 226 const std::string& default_group_name, 227 double entropy_value) { 228 return new FieldTrial(trial_name, total_probability, default_group_name, 229 entropy_value); 230 } 231 232 FieldTrial::FieldTrial(const std::string& trial_name, 233 const Probability total_probability, 234 const std::string& default_group_name, 235 double entropy_value) 236 : trial_name_(trial_name), 237 divisor_(total_probability), 238 default_group_name_(default_group_name), 239 random_(GetGroupBoundaryValue(total_probability, entropy_value)), 240 accumulated_group_probability_(0), 241 next_group_number_(kDefaultGroupNumber + 1), 242 group_(kNotFinalized), 243 enable_field_trial_(true), 244 forced_(false), 245 group_reported_(false), 246 trial_registered_(false) { 247 DCHECK_GT(total_probability, 0); 248 DCHECK(!trial_name_.empty()); 249 DCHECK(!default_group_name_.empty()); 250 } 251 252 FieldTrial::~FieldTrial() {} 253 254 void FieldTrial::SetTrialRegistered() { 255 DCHECK_EQ(kNotFinalized, group_); 256 DCHECK(!trial_registered_); 257 trial_registered_ = true; 258 } 259 260 void FieldTrial::SetGroupChoice(const std::string& group_name, int number) { 261 group_ = number; 262 if (group_name.empty()) 263 StringAppendF(&group_name_, "%d", group_); 264 else 265 group_name_ = group_name; 266 DVLOG(1) << "Field trial: " << trial_name_ << " Group choice:" << group_name_; 267 } 268 269 void FieldTrial::FinalizeGroupChoice() { 270 if (group_ != kNotFinalized) 271 return; 272 accumulated_group_probability_ = divisor_; 273 // Here it's OK to use |kDefaultGroupNumber| since we can't be forced and not 274 // finalized. 275 DCHECK(!forced_); 276 SetGroupChoice(default_group_name_, kDefaultGroupNumber); 277 } 278 279 bool FieldTrial::GetActiveGroup(ActiveGroup* active_group) const { 280 if (!group_reported_ || !enable_field_trial_) 281 return false; 282 DCHECK_NE(group_, kNotFinalized); 283 active_group->trial_name = trial_name_; 284 active_group->group_name = group_name_; 285 return true; 286 } 287 288 bool FieldTrial::GetState(State* field_trial_state) { 289 if (!enable_field_trial_) 290 return false; 291 FinalizeGroupChoice(); 292 field_trial_state->trial_name = trial_name_; 293 field_trial_state->group_name = group_name_; 294 field_trial_state->activated = group_reported_; 295 return true; 296 } 297 298 //------------------------------------------------------------------------------ 299 // FieldTrialList methods and members. 300 301 // static 302 FieldTrialList* FieldTrialList::global_ = NULL; 303 304 // static 305 bool FieldTrialList::used_without_global_ = false; 306 307 FieldTrialList::Observer::~Observer() { 308 } 309 310 FieldTrialList::FieldTrialList( 311 const FieldTrial::EntropyProvider* entropy_provider) 312 : entropy_provider_(entropy_provider), 313 observer_list_(new ObserverListThreadSafe<FieldTrialList::Observer>( 314 ObserverListBase<FieldTrialList::Observer>::NOTIFY_EXISTING_ONLY)) { 315 DCHECK(!global_); 316 DCHECK(!used_without_global_); 317 global_ = this; 318 319 Time two_years_from_build_time = GetBuildTime() + TimeDelta::FromDays(730); 320 Time::Exploded exploded; 321 two_years_from_build_time.LocalExplode(&exploded); 322 kNoExpirationYear = exploded.year; 323 } 324 325 FieldTrialList::~FieldTrialList() { 326 AutoLock auto_lock(lock_); 327 while (!registered_.empty()) { 328 RegistrationMap::iterator it = registered_.begin(); 329 it->second->Release(); 330 registered_.erase(it->first); 331 } 332 DCHECK_EQ(this, global_); 333 global_ = NULL; 334 } 335 336 // static 337 FieldTrial* FieldTrialList::FactoryGetFieldTrial( 338 const std::string& trial_name, 339 FieldTrial::Probability total_probability, 340 const std::string& default_group_name, 341 const int year, 342 const int month, 343 const int day_of_month, 344 FieldTrial::RandomizationType randomization_type, 345 int* default_group_number) { 346 return FactoryGetFieldTrialWithRandomizationSeed( 347 trial_name, total_probability, default_group_name, year, month, 348 day_of_month, randomization_type, 0, default_group_number, NULL); 349 } 350 351 // static 352 FieldTrial* FieldTrialList::FactoryGetFieldTrialWithRandomizationSeed( 353 const std::string& trial_name, 354 FieldTrial::Probability total_probability, 355 const std::string& default_group_name, 356 const int year, 357 const int month, 358 const int day_of_month, 359 FieldTrial::RandomizationType randomization_type, 360 uint32_t randomization_seed, 361 int* default_group_number, 362 const FieldTrial::EntropyProvider* override_entropy_provider) { 363 if (default_group_number) 364 *default_group_number = FieldTrial::kDefaultGroupNumber; 365 // Check if the field trial has already been created in some other way. 366 FieldTrial* existing_trial = Find(trial_name); 367 if (existing_trial) { 368 CHECK(existing_trial->forced_); 369 // If the default group name differs between the existing forced trial 370 // and this trial, then use a different value for the default group number. 371 if (default_group_number && 372 default_group_name != existing_trial->default_group_name()) { 373 // If the new default group number corresponds to the group that was 374 // chosen for the forced trial (which has been finalized when it was 375 // forced), then set the default group number to that. 376 if (default_group_name == existing_trial->group_name_internal()) { 377 *default_group_number = existing_trial->group_; 378 } else { 379 // Otherwise, use |kNonConflictingGroupNumber| (-2) for the default 380 // group number, so that it does not conflict with the |AppendGroup()| 381 // result for the chosen group. 382 const int kNonConflictingGroupNumber = -2; 383 static_assert( 384 kNonConflictingGroupNumber != FieldTrial::kDefaultGroupNumber, 385 "The 'non-conflicting' group number conflicts"); 386 static_assert(kNonConflictingGroupNumber != FieldTrial::kNotFinalized, 387 "The 'non-conflicting' group number conflicts"); 388 *default_group_number = kNonConflictingGroupNumber; 389 } 390 } 391 return existing_trial; 392 } 393 394 double entropy_value; 395 if (randomization_type == FieldTrial::ONE_TIME_RANDOMIZED) { 396 // If an override entropy provider is given, use it. 397 const FieldTrial::EntropyProvider* entropy_provider = 398 override_entropy_provider ? override_entropy_provider 399 : GetEntropyProviderForOneTimeRandomization(); 400 CHECK(entropy_provider); 401 entropy_value = entropy_provider->GetEntropyForTrial(trial_name, 402 randomization_seed); 403 } else { 404 DCHECK_EQ(FieldTrial::SESSION_RANDOMIZED, randomization_type); 405 DCHECK_EQ(0U, randomization_seed); 406 entropy_value = RandDouble(); 407 } 408 409 FieldTrial* field_trial = new FieldTrial(trial_name, total_probability, 410 default_group_name, entropy_value); 411 if (GetBuildTime() > CreateTimeFromParams(year, month, day_of_month)) 412 field_trial->Disable(); 413 FieldTrialList::Register(field_trial); 414 return field_trial; 415 } 416 417 // static 418 FieldTrial* FieldTrialList::Find(const std::string& trial_name) { 419 if (!global_) 420 return NULL; 421 AutoLock auto_lock(global_->lock_); 422 return global_->PreLockedFind(trial_name); 423 } 424 425 // static 426 int FieldTrialList::FindValue(const std::string& trial_name) { 427 FieldTrial* field_trial = Find(trial_name); 428 if (field_trial) 429 return field_trial->group(); 430 return FieldTrial::kNotFinalized; 431 } 432 433 // static 434 std::string FieldTrialList::FindFullName(const std::string& trial_name) { 435 FieldTrial* field_trial = Find(trial_name); 436 if (field_trial) 437 return field_trial->group_name(); 438 return std::string(); 439 } 440 441 // static 442 bool FieldTrialList::TrialExists(const std::string& trial_name) { 443 return Find(trial_name) != NULL; 444 } 445 446 // static 447 bool FieldTrialList::IsTrialActive(const std::string& trial_name) { 448 FieldTrial* field_trial = Find(trial_name); 449 FieldTrial::ActiveGroup active_group; 450 return field_trial && field_trial->GetActiveGroup(&active_group); 451 } 452 453 // static 454 void FieldTrialList::StatesToString(std::string* output) { 455 FieldTrial::ActiveGroups active_groups; 456 GetActiveFieldTrialGroups(&active_groups); 457 for (FieldTrial::ActiveGroups::const_iterator it = active_groups.begin(); 458 it != active_groups.end(); ++it) { 459 DCHECK_EQ(std::string::npos, 460 it->trial_name.find(kPersistentStringSeparator)); 461 DCHECK_EQ(std::string::npos, 462 it->group_name.find(kPersistentStringSeparator)); 463 output->append(it->trial_name); 464 output->append(1, kPersistentStringSeparator); 465 output->append(it->group_name); 466 output->append(1, kPersistentStringSeparator); 467 } 468 } 469 470 // static 471 void FieldTrialList::AllStatesToString(std::string* output) { 472 if (!global_) 473 return; 474 AutoLock auto_lock(global_->lock_); 475 476 for (const auto& registered : global_->registered_) { 477 FieldTrial::State trial; 478 if (!registered.second->GetState(&trial)) 479 continue; 480 DCHECK_EQ(std::string::npos, 481 trial.trial_name.find(kPersistentStringSeparator)); 482 DCHECK_EQ(std::string::npos, 483 trial.group_name.find(kPersistentStringSeparator)); 484 if (trial.activated) 485 output->append(1, kActivationMarker); 486 trial.trial_name.AppendToString(output); 487 output->append(1, kPersistentStringSeparator); 488 trial.group_name.AppendToString(output); 489 output->append(1, kPersistentStringSeparator); 490 } 491 } 492 493 // static 494 void FieldTrialList::GetActiveFieldTrialGroups( 495 FieldTrial::ActiveGroups* active_groups) { 496 DCHECK(active_groups->empty()); 497 if (!global_) 498 return; 499 AutoLock auto_lock(global_->lock_); 500 501 for (RegistrationMap::iterator it = global_->registered_.begin(); 502 it != global_->registered_.end(); ++it) { 503 FieldTrial::ActiveGroup active_group; 504 if (it->second->GetActiveGroup(&active_group)) 505 active_groups->push_back(active_group); 506 } 507 } 508 509 // static 510 void FieldTrialList::GetActiveFieldTrialGroupsFromString( 511 const std::string& trials_string, 512 FieldTrial::ActiveGroups* active_groups) { 513 std::vector<FieldTrial::State> entries; 514 if (!ParseFieldTrialsString(trials_string, &entries)) 515 return; 516 517 for (const auto& entry : entries) { 518 if (entry.activated) { 519 FieldTrial::ActiveGroup group; 520 group.trial_name = entry.trial_name.as_string(); 521 group.group_name = entry.group_name.as_string(); 522 active_groups->push_back(group); 523 } 524 } 525 } 526 527 // static 528 bool FieldTrialList::CreateTrialsFromString( 529 const std::string& trials_string, 530 const std::set<std::string>& ignored_trial_names) { 531 DCHECK(global_); 532 if (trials_string.empty() || !global_) 533 return true; 534 535 std::vector<FieldTrial::State> entries; 536 if (!ParseFieldTrialsString(trials_string, &entries)) 537 return false; 538 539 for (const auto& entry : entries) { 540 const std::string trial_name = entry.trial_name.as_string(); 541 const std::string group_name = entry.group_name.as_string(); 542 543 if (ContainsKey(ignored_trial_names, trial_name)) 544 continue; 545 546 FieldTrial* trial = CreateFieldTrial(trial_name, group_name); 547 if (!trial) 548 return false; 549 if (entry.activated) { 550 // Call |group()| to mark the trial as "used" and notify observers, if 551 // any. This is useful to ensure that field trials created in child 552 // processes are properly reported in crash reports. 553 trial->group(); 554 } 555 } 556 return true; 557 } 558 559 // static 560 FieldTrial* FieldTrialList::CreateFieldTrial( 561 const std::string& name, 562 const std::string& group_name) { 563 DCHECK(global_); 564 DCHECK_GE(name.size(), 0u); 565 DCHECK_GE(group_name.size(), 0u); 566 if (name.empty() || group_name.empty() || !global_) 567 return NULL; 568 569 FieldTrial* field_trial = FieldTrialList::Find(name); 570 if (field_trial) { 571 // In single process mode, or when we force them from the command line, 572 // we may have already created the field trial. 573 if (field_trial->group_name_internal() != group_name) 574 return NULL; 575 return field_trial; 576 } 577 const int kTotalProbability = 100; 578 field_trial = new FieldTrial(name, kTotalProbability, group_name, 0); 579 FieldTrialList::Register(field_trial); 580 // Force the trial, which will also finalize the group choice. 581 field_trial->SetForced(); 582 return field_trial; 583 } 584 585 // static 586 void FieldTrialList::AddObserver(Observer* observer) { 587 if (!global_) 588 return; 589 global_->observer_list_->AddObserver(observer); 590 } 591 592 // static 593 void FieldTrialList::RemoveObserver(Observer* observer) { 594 if (!global_) 595 return; 596 global_->observer_list_->RemoveObserver(observer); 597 } 598 599 // static 600 void FieldTrialList::NotifyFieldTrialGroupSelection(FieldTrial* field_trial) { 601 if (!global_) 602 return; 603 604 { 605 AutoLock auto_lock(global_->lock_); 606 if (field_trial->group_reported_) 607 return; 608 field_trial->group_reported_ = true; 609 } 610 611 if (!field_trial->enable_field_trial_) 612 return; 613 614 global_->observer_list_->Notify( 615 FROM_HERE, &FieldTrialList::Observer::OnFieldTrialGroupFinalized, 616 field_trial->trial_name(), field_trial->group_name_internal()); 617 } 618 619 // static 620 size_t FieldTrialList::GetFieldTrialCount() { 621 if (!global_) 622 return 0; 623 AutoLock auto_lock(global_->lock_); 624 return global_->registered_.size(); 625 } 626 627 // static 628 const FieldTrial::EntropyProvider* 629 FieldTrialList::GetEntropyProviderForOneTimeRandomization() { 630 if (!global_) { 631 used_without_global_ = true; 632 return NULL; 633 } 634 635 return global_->entropy_provider_.get(); 636 } 637 638 FieldTrial* FieldTrialList::PreLockedFind(const std::string& name) { 639 RegistrationMap::iterator it = registered_.find(name); 640 if (registered_.end() == it) 641 return NULL; 642 return it->second; 643 } 644 645 // static 646 void FieldTrialList::Register(FieldTrial* trial) { 647 if (!global_) { 648 used_without_global_ = true; 649 return; 650 } 651 AutoLock auto_lock(global_->lock_); 652 CHECK(!global_->PreLockedFind(trial->trial_name())) << trial->trial_name(); 653 trial->AddRef(); 654 trial->SetTrialRegistered(); 655 global_->registered_[trial->trial_name()] = trial; 656 } 657 658 } // namespace base 659