feat: Add FieldTrails API. (#146)

Author: cloudwebrtc

BUILD.gn

@@ -77,6 +77,7 @@ rtc_shared_library("libwebrtc") {
     "include/rtc_data_packet_cryptor.h",
     "include/rtc_dtls_transport.h",
     "include/rtc_dtmf_sender.h",
+    "include/rtc_field_trials.h",
     "include/rtc_frame_cryptor.h",
     "include/rtc_ice_candidate.h",
     "include/rtc_media_stream.h",
@@ -125,6 +126,8 @@ rtc_shared_library("libwebrtc") {
     "src/rtc_dtls_transport_impl.h",
     "src/rtc_dtmf_sender_impl.cc",
     "src/rtc_dtmf_sender_impl.h",
+    "src/rtc_field_trials.cc",
+    "src/rtc_field_trials_impl.h",
     "src/rtc_frame_cryptor_impl.cc",
     "src/rtc_frame_cryptor_impl.h",
     "src/rtc_ice_candidate_impl.cc",
@@ -250,6 +253,7 @@ rtc_shared_library("libwebrtc") {
 
   deps = [
     "../api:create_peerconnection_factory",
+    "../api:field_trials",
     "../api:libjingle_peerconnection_api",
     "../api/audio_codecs:builtin_audio_decoder_factory",
     "../api/audio_codecs:builtin_audio_encoder_factory",
@@ -310,6 +314,7 @@ rtc_test("libwebrtc_cpp_api_unittests") {
   testonly = true
 
   sources = [
+     "test/field_trials.test.cc",
      "test/peerconnection_factory.test.cc",
   ]
 
@@ -325,4 +330,4 @@ rtc_test("libwebrtc_cpp_api_unittests") {
     "//test:test_support",
     "//test:test_main",
   ]
-}
+}

include/libwebrtc.h

@@ -30,6 +30,23 @@ class LibWebRTC {
    */
   LIB_WEBRTC_API static bool Initialize();
 
+  /**
+   * @brief Applies the given field trials and initializes WebRTC.
+   *
+   * Configures the global WebRTC field trials and then performs the same
+   * initialization as Initialize(). Field trials are read when objects are
+   * created, so this must be called before any other call into WebRTC, in
+   * particular before CreateRTCPeerConnectionFactory().
+   *
+   * Each entry is either "Key/Value" or "Key/Value/", e.g.
+   * "WebRTC-FlexFEC-03/Enabled/". See rtc_field_trials.h for the well known
+   * keys and for finer grained control over the field trials.
+   *
+   * @param field_trials The field trial entries to apply.
+   */
+  LIB_WEBRTC_API static void InitializeWithFieldTrials(
+      vector<string> field_trials);
+
   /**
    * @brief Creates a new WebRTC PeerConnectionFactory.
    *

include/rtc_field_trials.h

@@ -0,0 +1,117 @@
+#ifndef LIB_WEBRTC_RTC_FIELD_TRIALS_HXX
+#define LIB_WEBRTC_RTC_FIELD_TRIALS_HXX
+
+#include "rtc_types.h"
+
+namespace libwebrtc {
+
+/**
+ * The only valid value for the following keys, if set, is
+ * kRTCFieldTrialEnabledValue.
+ */
+constexpr char kRTCFieldTrialAudioForceABWENoTWCCKey[] =
+    "WebRTC-Audio-ABWENoTWCC";
+constexpr char kRTCFieldTrialFlexFec03AdvertisedKey[] =
+    "WebRTC-FlexFEC-03-Advertised";
+constexpr char kRTCFieldTrialFlexFec03Key[] = "WebRTC-FlexFEC-03";
+constexpr char kRTCFieldTrialH264HighProfileKey[] = "WebRTC-H264HighProfile";
+constexpr char kRTCFieldTrialMinimizeResamplingOnMobileKey[] =
+    "WebRTC-Audio-MinimizeResamplingOnMobile";
+constexpr char kRTCFieldTrialUseNWPathMonitorKey[] =
+    "WebRTC-Network-UseNWPathMonitor";
+constexpr char kRTCFieldTrialIceHandshakeDtlsKey[] = "WebRTC-IceHandshakeDtls";
+
+/** The valid value for the field trials above. */
+constexpr char kRTCFieldTrialEnabledValue[] = "Enabled";
+
+/** The value used to explicitly turn a field trial off. */
+constexpr char kRTCFieldTrialDisabledValue[] = "Disabled";
+
+/**
+ * @class RTCFieldTrials
+ * @brief Configures and queries the global WebRTC field trials.
+ *
+ * Field trials allow clients to turn on feature code that is not enabled by
+ * default. They must be initialized before any other call into WebRTC, i.e.
+ * before LibWebRTC::Initialize() and before any peer connection factory is
+ * created, otherwise the objects already created keep using the previous
+ * configuration.
+ *
+ * A field trial is described by a "Key/Value" pair, where the key is one of
+ * the constants above (or any other trial name known to WebRTC) and the value
+ * is the group to assign the process to, usually kRTCFieldTrialEnabledValue.
+ *
+ * See also: webrtc/system_wrappers/include/field_trial.h
+ */
+class RTCFieldTrials {
+ public:
+  /**
+   * @brief Assembles a WebRTC field trial string out of a list of entries.
+   *
+   * Each entry is either "Key/Value" or "Key/Value/"; empty entries are
+   * skipped. The returned string is the concatenation of all the entries in
+   * the canonical "Key1/Value1/Key2/Value2/" form. No extra format checking is
+   * performed here, that is done by the underlying WebRTC calls.
+   *
+   * @param field_trials The field trial entries.
+   * @return The assembled field trial string.
+   */
+  LIB_WEBRTC_API static string BuildFieldTrialsString(
+      const vector<string>& field_trials);
+
+  /**
+   * @brief Initializes the global field trials from a list of entries.
+   *
+   * Convenience wrapper around BuildFieldTrialsString() followed by
+   * InitFieldTrialsFromString(). Must be called before any other call into
+   * WebRTC.
+   *
+   * @param field_trials The field trial entries, e.g.
+   * {"WebRTC-FlexFEC-03/Enabled/"}.
+   * @return true if the field trials were applied, false if the resulting
+   * string is invalid.
+   */
+  LIB_WEBRTC_API static bool InitFieldTrials(
+      const vector<string>& field_trials);
+
+  /**
+   * @brief Initializes the global field trials from a string.
+   *
+   * The string must be in the "Key1/Value1/Key2/Value2/" form, note the
+   * trailing separator. An empty string clears every previously configured
+   * trial. Must be called before any other call into WebRTC.
+   *
+   * @param trials_string The field trial string.
+   * @return true if the string is valid and was applied, false otherwise.
+   */
+  LIB_WEBRTC_API static bool InitFieldTrialsFromString(
+      const string& trials_string);
+
+  /**
+   * @brief Returns the field trial string currently in use, or an empty
+   * string if none was configured.
+   */
+  LIB_WEBRTC_API static string GetFieldTrialsString();
+
+  /**
+   * @brief Returns the group the process is assigned to for `key`, or an
+   * empty string if the trial is not configured.
+   */
+  LIB_WEBRTC_API static string Lookup(const string& key);
+
+  /**
+   * @brief Returns true if the group configured for `key` starts with
+   * "Enabled".
+   */
+  LIB_WEBRTC_API static bool IsEnabled(const string& key);
+
+  /**
+   * @brief Returns true if the group configured for `key` starts with
+   * "Disabled".
+   */
+  LIB_WEBRTC_API static bool IsDisabled(const string& key);
+};
+
+}  // namespace libwebrtc
+
+#endif  // LIB_WEBRTC_RTC_FIELD_TRIALS_HXX

src/libwebrtc.cc

@@ -3,6 +3,7 @@
 #include "api/scoped_refptr.h"
 #include "rtc_base/ssl_adapter.h"
 #include "rtc_base/thread.h"
+#include "rtc_field_trials.h"
 #include "rtc_peerconnection_factory_impl.h"
 
 namespace libwebrtc {
@@ -19,6 +20,13 @@ bool LibWebRTC::Initialize() {
   return g_is_initialized;
 }
 
+// Applies the field trials before initializing SSL, so that everything created
+// afterwards picks them up.
+void LibWebRTC::InitializeWithFieldTrials(vector<string> field_trials) {
+  RTCFieldTrials::InitFieldTrials(field_trials);
+  Initialize();
+}
+
 // Stops and cleans up the threads and SSL.
 void LibWebRTC::Terminate() {
   webrtc::ThreadManager::Instance()->SetCurrentThread(NULL);

src/rtc_field_trials.cc

@@ -0,0 +1,109 @@
+#include "rtc_field_trials.h"
+
+#include <memory>
+#include <mutex>
+#include <string>
+#include <utility>
+
+#include "api/field_trials.h"
+#include "rtc_base/logging.h"
+#include "rtc_field_trials_impl.h"
+
+namespace libwebrtc {
+
+namespace {
+
+constexpr char kFieldTrialSeparator = '/';
+
+std::mutex& FieldTrialsLock() {
+  static std::mutex* lock = new std::mutex();
+  return *lock;
+}
+
+std::string& FieldTrialsString() {
+  static std::string* trials_string = new std::string();
+  return *trials_string;
+}
+
+std::unique_ptr<webrtc::FieldTrials>& GlobalFieldTrials() {
+  static std::unique_ptr<webrtc::FieldTrials>* field_trials =
+      new std::unique_ptr<webrtc::FieldTrials>();
+  return *field_trials;
+}
+
+}  // namespace
+
+std::unique_ptr<webrtc::FieldTrialsView> CopyGlobalFieldTrials() {
+  std::lock_guard<std::mutex> lock(FieldTrialsLock());
+  const std::unique_ptr<webrtc::FieldTrials>& field_trials =
+      GlobalFieldTrials();
+  return field_trials == nullptr ? nullptr : field_trials->CreateCopy();
+}
+
+string RTCFieldTrials::BuildFieldTrialsString(
+    const vector<string>& field_trials) {
+  // We don't perform any extra format checking. That should be done by the
+  // underlying WebRTC calls.
+  std::string trials_string;
+  for (size_t i = 0; i < field_trials.size(); ++i) {
+    std::string entry = field_trials[i].std_string();
+    if (entry.empty()) {
+      continue;
+    }
+    trials_string += entry;
+    if (entry.back() != kFieldTrialSeparator) {
+      trials_string += kFieldTrialSeparator;
+    }
+  }
+  return string(trials_string);
+}
+
+bool RTCFieldTrials::InitFieldTrials(const vector<string>& field_trials) {
+  return InitFieldTrialsFromString(BuildFieldTrialsString(field_trials));
+}
+
+bool RTCFieldTrials::InitFieldTrialsFromString(const string& trials_string) {
+  std::string trials = trials_string.std_string();
+  std::unique_ptr<webrtc::FieldTrials> parsed =
+      webrtc::FieldTrials::Create(trials);
+  if (parsed == nullptr) {
+    RTC_LOG(LS_ERROR) << "Invalid field trials string: " << trials;
+    return false;
+  }
+
+  std::lock_guard<std::mutex> lock(FieldTrialsLock());
+  GlobalFieldTrials() = std::move(parsed);
+  FieldTrialsString() = trials;
+  RTC_LOG(LS_INFO) << "Field trials set to: " << trials;
+  return true;
+}
+
+string RTCFieldTrials::GetFieldTrialsString() {
+  std::lock_guard<std::mutex> lock(FieldTrialsLock());
+  return string(FieldTrialsString());
+}
+
+string RTCFieldTrials::Lookup(const string& key) {
+  std::lock_guard<std::mutex> lock(FieldTrialsLock());
+  const std::unique_ptr<webrtc::FieldTrials>& field_trials =
+      GlobalFieldTrials();
+  return string(field_trials == nullptr
+                    ? std::string()
+                    : field_trials->Lookup(key.std_string()));
+}
+
+bool RTCFieldTrials::IsEnabled(const string& key) {
+  std::lock_guard<std::mutex> lock(FieldTrialsLock());
+  const std::unique_ptr<webrtc::FieldTrials>& field_trials =
+      GlobalFieldTrials();
+  return field_trials != nullptr && field_trials->IsEnabled(key.std_string());
+}
+
+bool RTCFieldTrials::IsDisabled(const string& key) {
+  std::lock_guard<std::mutex> lock(FieldTrialsLock());
+  const std::unique_ptr<webrtc::FieldTrials>& field_trials =
+      GlobalFieldTrials();
+  return field_trials != nullptr && field_trials->IsDisabled(key.std_string());
+}
+
+}  // namespace libwebrtc

src/rtc_field_trials_impl.h

@@ -0,0 +1,19 @@
+#ifndef LIB_WEBRTC_RTC_FIELD_TRIALS_IMPL_HXX
+#define LIB_WEBRTC_RTC_FIELD_TRIALS_IMPL_HXX
+
+#include <memory>
+
+#include "api/field_trials_view.h"
+
+namespace libwebrtc {
+
+/**
+ * Returns a snapshot of the field trials configured through RTCFieldTrials,
+ * or nullptr when none were configured. Used to build the webrtc::Environment
+ * of the objects created by this library.
+ */
+std::unique_ptr<webrtc::FieldTrialsView> CopyGlobalFieldTrials();
+
+}  // namespace libwebrtc
+
+#endif  // LIB_WEBRTC_RTC_FIELD_TRIALS_IMPL_HXX

src/rtc_peerconnection_factory_impl.cc

@@ -9,6 +9,7 @@
 #include "api/video_codecs/builtin_video_encoder_factory.h"
 #include "modules/audio_device/audio_device_impl.h"
 #include "rtc_audio_source_impl.h"
+#include "rtc_field_trials_impl.h"
 #include "rtc_media_stream_impl.h"
 #include "rtc_mediaconstraints_impl.h"
 #include "rtc_peerconnection_impl.h"
@@ -45,8 +46,20 @@ std::unique_ptr<webrtc::VideoDecoderFactory> CreateIntelVideoDecoderFactory() {
 }
 #endif
 
+namespace {
+
+// Builds the environment shared by everything this factory creates, applying
+// the field trials configured through RTCFieldTrials, if any.
+webrtc::Environment CreateEnvironmentWithFieldTrials() {
+  webrtc::EnvironmentFactory factory;
+  factory.Set(CopyGlobalFieldTrials());
+  return factory.Create();
+}
+
+}  // namespace
+
 RTCPeerConnectionFactoryImpl::RTCPeerConnectionFactoryImpl():
-env_(webrtc::EnvironmentFactory().Create()) {}
+env_(CreateEnvironmentWithFieldTrials()) {}
 
 RTCPeerConnectionFactoryImpl::~RTCPeerConnectionFactoryImpl() {}