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
|
/*
* Copyright 2023 The WebRTC Project Authors. All rights reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
// This header file provides wrapper for common WebRTC utilities.
// Different application may need different implementations of these utilities,
// Moreover, single application may need to use WebRTC for multiple purposes,
// and thus would need to provide different utilities implementations for
// different peer connections.
// The main purpose of the `Environment` class below is to propagate references
// to those utilities to all WebRTC classes that need them.
#ifndef API_ENVIRONMENT_ENVIRONMENT_H_
#define API_ENVIRONMENT_ENVIRONMENT_H_
#include <utility>
#include "absl/base/nullability.h"
#include "api/ref_counted_base.h"
#include "api/scoped_refptr.h"
#include "rtc_base/system/rtc_export.h"
namespace webrtc {
// These classes are forward declared to keep Environment dependencies
// lightweight. Users who need any of the types below should include their
// header explicitely.
class Clock;
class TaskQueueFactory;
class FieldTrialsView;
class RtcEventLog;
// Contains references to WebRTC utilities. Object of this class should be
// passed as a construction parameter and saved by value in each class that
// needs it. Most classes shouldn't create a new instance of the `Environment`,
// but instead should use a propagated copy.
// Usually Environment should be the first parameter in a constructor or a
// factory, and the first member in the class. Keeping Environment as the first
// member in the class ensures utilities (e.g. clock) are still valid during
// destruction of other members.
//
// Example:
// class PeerConnection {
// public:
// PeerConnection(const Environment& env, ...)
// : env_(env),
// log_duration_on_destruction_(&env_.clock()),
// rtp_manager_(env_, ...),
// ...
//
// const FieldTrialsView& trials() const { return env_.field_trials(); }
//
// scoped_refptr<RtpTransceiverInterface> AddTransceiver(...) {
// return make_ref_counted<RtpTransceiverImpl>(env_, ...);
// }
//
// private:
// const Environment env_;
// Stats log_duration_on_destruction_;
// RtpTransmissionManager rtp_manager_;
// };
// This class is thread safe.
class RTC_EXPORT Environment final {
public:
// Default constructor is deleted in favor of creating this object using
// `EnvironmentFactory`. To create the default environment use
// `EnvironmentFactory().Create()` or `CreateEnvironment()`.
Environment() = delete;
Environment(const Environment&) = default;
Environment(Environment&&) = default;
Environment& operator=(const Environment&) = default;
Environment& operator=(Environment&&) = default;
~Environment() = default;
// Provides means to alter behavior, mostly for A/B testing new features.
// See ../../g3doc/field-trials.md
const FieldTrialsView& field_trials() const;
// Provides an interface to query current time.
// See ../../g3doc/implementation_basics.md#time
Clock& clock() const;
// Provides a factory for task queues, WebRTC threading primitives.
// See ../../g3doc/implementation_basics.md#threads
TaskQueueFactory& task_queue_factory() const;
// Provides an interface for collecting structured logs.
// See ../../logging/g3doc/rtc_event_log.md
RtcEventLog& event_log() const;
private:
friend class EnvironmentFactory;
Environment(scoped_refptr<const rtc::RefCountedBase> storage,
absl::Nonnull<const FieldTrialsView*> field_trials,
absl::Nonnull<Clock*> clock,
absl::Nonnull<TaskQueueFactory*> task_queue_factory,
absl::Nonnull<RtcEventLog*> event_log)
: storage_(std::move(storage)),
field_trials_(field_trials),
clock_(clock),
task_queue_factory_(task_queue_factory),
event_log_(event_log) {}
// Container that keeps ownership of the utilities below.
// Defining this as a RefCountedBase allows `Environment` to share this
// storage with another `Environment`, in particular allows `Environment` to
// be copyable. It is up to the `EnvironmentFactory` to provide an object that
// ensures references to utilties below are valid while object in the
// `storage_` is alive.
scoped_refptr<const rtc::RefCountedBase> storage_;
absl::Nonnull<const FieldTrialsView*> field_trials_;
absl::Nonnull<Clock*> clock_;
absl::Nonnull<TaskQueueFactory*> task_queue_factory_;
absl::Nonnull<RtcEventLog*> event_log_;
};
//------------------------------------------------------------------------------
// Implementation details follow
//------------------------------------------------------------------------------
inline const FieldTrialsView& Environment::field_trials() const {
return *field_trials_;
}
inline Clock& Environment::clock() const {
return *clock_;
}
inline TaskQueueFactory& Environment::task_queue_factory() const {
return *task_queue_factory_;
}
inline RtcEventLog& Environment::event_log() const {
return *event_log_;
}
} // namespace webrtc
#endif // API_ENVIRONMENT_ENVIRONMENT_H_
|
