environment.h (5335B)
1 /* 2 * Copyright 2023 The WebRTC Project Authors. All rights reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 // This header file provides wrapper for common WebRTC utilities. 12 // Different application may need different implementations of these utilities, 13 // Moreover, single application may need to use WebRTC for multiple purposes, 14 // and thus would need to provide different utilities implementations for 15 // different peer connections. 16 // The main purpose of the `Environment` class below is to propagate references 17 // to those utilities to all WebRTC classes that need them. 18 19 #ifndef API_ENVIRONMENT_ENVIRONMENT_H_ 20 #define API_ENVIRONMENT_ENVIRONMENT_H_ 21 22 #include <utility> 23 24 #include "absl/base/nullability.h" 25 #include "api/field_trials_view.h" 26 #include "api/ref_counted_base.h" 27 #include "api/rtc_event_log/rtc_event_log.h" 28 #include "api/scoped_refptr.h" 29 #include "api/task_queue/task_queue_factory.h" 30 #include "rtc_base/system/rtc_export.h" 31 #include "system_wrappers/include/clock.h" 32 33 namespace webrtc { 34 // Contains references to WebRTC utilities. Object of this class should be 35 // passed as a construction parameter and saved by value in each class that 36 // needs it. Most classes shouldn't create a new instance of the `Environment`, 37 // but instead should use a propagated copy. 38 // Usually Environment should be the first parameter in a constructor or a 39 // factory, and the first member in the class. Keeping Environment as the first 40 // member in the class ensures utilities (e.g. clock) are still valid during 41 // destruction of other members. 42 // 43 // Example: 44 // class PeerConnection { 45 // public: 46 // PeerConnection(const Environment& env, ...) 47 // : env_(env), 48 // log_duration_on_destruction_(&env_.clock()), 49 // rtp_manager_(env_, ...), 50 // ... 51 // 52 // const FieldTrialsView& trials() const { return env_.field_trials(); } 53 // 54 // scoped_refptr<RtpTransceiverInterface> AddTransceiver(...) { 55 // return make_ref_counted<RtpTransceiverImpl>(env_, ...); 56 // } 57 // 58 // private: 59 // const Environment env_; 60 // Stats log_duration_on_destruction_; 61 // RtpTransmissionManager rtp_manager_; 62 // }; 63 // This class is thread safe. 64 class RTC_EXPORT Environment final { 65 public: 66 // Default constructor is deleted in favor of creating this object using 67 // `EnvironmentFactory`. To create the default environment use 68 // `EnvironmentFactory().Create()` or `CreateEnvironment()`. 69 Environment() = delete; 70 71 Environment(const Environment&) = default; 72 Environment(Environment&&) = default; 73 Environment& operator=(const Environment&) = default; 74 Environment& operator=(Environment&&) = default; 75 76 ~Environment() = default; 77 78 // Provides means to alter behavior, mostly for A/B testing new features. 79 // See ../../g3doc/field-trials.md 80 const FieldTrialsView& field_trials() const; 81 82 // Provides an interface to query current time. 83 // See ../../g3doc/implementation_basics.md#time 84 Clock& clock() const; 85 86 // Provides a factory for task queues, WebRTC threading primitives. 87 // See ../../g3doc/implementation_basics.md#threads 88 TaskQueueFactory& task_queue_factory() const; 89 90 // Provides an interface for collecting structured logs. 91 // See ../../logging/g3doc/rtc_event_log.md 92 RtcEventLog& event_log() const; 93 94 private: 95 friend class EnvironmentFactory; 96 Environment(scoped_refptr<const RefCountedBase> storage, 97 const FieldTrialsView* absl_nonnull field_trials, 98 Clock* absl_nonnull clock, 99 TaskQueueFactory* absl_nonnull task_queue_factory, 100 RtcEventLog* absl_nonnull event_log) 101 : storage_(std::move(storage)), 102 field_trials_(field_trials), 103 clock_(clock), 104 task_queue_factory_(task_queue_factory), 105 event_log_(event_log) {} 106 107 // Container that keeps ownership of the utilities below. 108 // Defining this as a RefCountedBase allows `Environment` to share this 109 // storage with another `Environment`, in particular allows `Environment` to 110 // be copyable. It is up to the `EnvironmentFactory` to provide an object that 111 // ensures references to utilties below are valid while object in the 112 // `storage_` is alive. 113 scoped_refptr<const RefCountedBase> storage_; 114 115 const FieldTrialsView* absl_nonnull field_trials_; 116 Clock* absl_nonnull clock_; 117 TaskQueueFactory* absl_nonnull task_queue_factory_; 118 RtcEventLog* absl_nonnull event_log_; 119 }; 120 121 //------------------------------------------------------------------------------ 122 // Implementation details follow 123 //------------------------------------------------------------------------------ 124 125 inline const FieldTrialsView& Environment::field_trials() const { 126 return *field_trials_; 127 } 128 129 inline Clock& Environment::clock() const { 130 return *clock_; 131 } 132 133 inline TaskQueueFactory& Environment::task_queue_factory() const { 134 return *task_queue_factory_; 135 } 136 137 inline RtcEventLog& Environment::event_log() const { 138 return *event_log_; 139 } 140 141 } // namespace webrtc 142 143 #endif // API_ENVIRONMENT_ENVIRONMENT_H_