environment.h - mozsearch

Enable keyboard shortcuts

/*

 *  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_