RTCStats and RTCStatsReport added (webrtc/stats).
The old and new getStats are very different. This CL proposes rewriting
the new getStats from scratch with a bottom-up approach, starting with
the fundamental stats classes. This will allow cleaner and more
efficient code that is more aligned with the spec.
RTCStats and subclasses are the equivalent to RTCStats and RTCStats-
-derived dictionaries from the specs[1][2]. The dictionary members are
public member variables of type RTCStatsMember<T>, where T is one of the
supported types. All members derive from RTCStatsMemberInterface and
iteration of members is possible with RTCStats::Members().
The members are not stored in a map for performance and readability.
Type checking is supported with static class variables, kType.
Only the supported member types T are specialized and may be
instantiated, and sequences are supported with std::vector<...>. Type
checking is again supported with static class variables, kType.
RTCStatsReport is the equivalent from the spec[3], and maps RTCStats::id
to RTCStats-objects. RTCStatsReport is reference counted. It and its
contained stats may be destroyed on any thread. When the
RTCStatsCollector is added in a follow-up CL, it will return const
references to the RTCStatsReports. This means copies don't have to be
made for multiple stats observers or when jumping threads. In fact, no
copies of any stats will have to be made in surfacing stats to Blink.
[1] https://www.w3.org/TR/2016/WD-webrtc-20160531/#rtcstats-dictionary
[2] https://w3c.github.io/webrtc-stats/archives/20160526/webrtc-stats.html
[3] https://www.w3.org/TR/2016/WD-webrtc-20160531/#rtcstatsreport-object
This adds the new folder webrtc/stats/, with target rtc_stats and binary
rtc_stats_unittests. Public api headers are placed in webrtc/api/ and
.cc files are placed in webrtc/stats/.
BUG=chromium:627816
Review-Url: https://codereview.webrtc.org/2241093002
Cr-Commit-Position: refs/heads/master@{#13879}
diff --git a/webrtc/api/BUILD.gn b/webrtc/api/BUILD.gn
index d06439f..a1a4a86 100644
--- a/webrtc/api/BUILD.gn
+++ b/webrtc/api/BUILD.gn
@@ -69,6 +69,8 @@
"proxy.h",
"remoteaudiosource.cc",
"remoteaudiosource.h",
+ "rtcstats.h",
+ "rtcstatsreport.h",
"rtpparameters.h",
"rtpreceiver.cc",
"rtpreceiver.h",
diff --git a/webrtc/api/api.gyp b/webrtc/api/api.gyp
index 86a55fd..f9f846b 100644
--- a/webrtc/api/api.gyp
+++ b/webrtc/api/api.gyp
@@ -144,6 +144,8 @@
'proxy.h',
'remoteaudiosource.cc',
'remoteaudiosource.h',
+ 'rtcstats.h',
+ 'rtcstatsreport.h',
'rtpparameters.h',
'rtpreceiver.cc',
'rtpreceiver.h',
diff --git a/webrtc/api/rtcstats.h b/webrtc/api/rtcstats.h
new file mode 100644
index 0000000..4b2d70f
--- /dev/null
+++ b/webrtc/api/rtcstats.h
@@ -0,0 +1,283 @@
+/*
+ * Copyright 2016 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.
+ */
+
+#ifndef WEBRTC_API_RTCSTATS_H_
+#define WEBRTC_API_RTCSTATS_H_
+
+#include <map>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "webrtc/base/checks.h"
+
+namespace webrtc {
+
+class RTCStatsMemberInterface;
+
+// Abstract base class for RTCStats-derived dictionaries, see
+// https://w3c.github.io/webrtc-stats/.
+//
+// All derived classes must have the following static variable defined:
+// static const char kType[];
+// It is used as a unique class identifier and a string representation of the
+// class type, see https://w3c.github.io/webrtc-stats/#rtcstatstype-str*.
+// Use the |WEBRTC_RTCSTATS_IMPL| macro when implementing subclasses, see macro
+// for details.
+//
+// Derived classes list their dictionary members, RTCStatsMember<T>, as public
+// fields, allowing the following:
+//
+// RTCFooStats foo("fooId", GetCurrentTime());
+// foo.bar = 42;
+// foo.baz = std::vector<std::string>();
+// foo.baz->push_back("hello world");
+// uint32_t x = *foo.bar;
+//
+// Pointers to all the members are available with |Members|, allowing iteration:
+//
+// for (const RTCStatsMemberInterface* member : foo.Members()) {
+// printf("%s = %s\n", member->name(), member->ValueToString().c_str());
+// }
+class RTCStats {
+ public:
+ RTCStats(const std::string& id, double timestamp)
+ : id_(id), timestamp_(timestamp) {}
+ RTCStats(std::string&& id, double timestamp)
+ : id_(std::move(id)), timestamp_(timestamp) {}
+ virtual ~RTCStats() {}
+
+ virtual std::unique_ptr<RTCStats> copy() const = 0;
+
+ const std::string& id() const { return id_; }
+ // Time relative to the UNIX epoch (Jan 1, 1970, UTC), in seconds.
+ double timestamp() const { return timestamp_; }
+ // Returns the static member variable |kType| of the implementing class.
+ virtual const char* type() const = 0;
+ // Returns a vector of pointers to all the RTCStatsMemberInterface members of
+ // this class. This allows for iteration of members.
+ std::vector<const RTCStatsMemberInterface*> Members() const;
+
+ // Creates a human readable string representation of the report, listing all
+ // of its members (names and values).
+ std::string ToString() const;
+
+ // Downcasts the stats object to an |RTCStats| subclass |T|. DCHECKs that the
+ // object is of type |T|.
+ template<typename T>
+ const T& cast_to() const {
+ RTC_DCHECK_EQ(type(), T::kType);
+ return static_cast<const T&>(*this);
+ }
+
+ protected:
+ // Gets a vector of all members of this |RTCStats| object, including members
+ // derived from parent classes. |additional_capacity| is how many more members
+ // shall be reserved in the vector (so that subclasses can allocate a vector
+ // with room for both parent and child members without it having to resize).
+ virtual std::vector<const RTCStatsMemberInterface*>
+ MembersOfThisObjectAndAncestors(
+ size_t additional_capacity) const;
+
+ std::string const id_;
+ double timestamp_;
+};
+
+// All |RTCStats| classes should use this macro in a public section of the class
+// definition.
+//
+// This macro declares the static |kType| and overrides methods as required by
+// subclasses of |RTCStats|: |copy|, |type|, and
+// |MembersOfThisObjectAndAncestors|. The |...| argument is a list of addresses
+// to each member defined in the implementing class (list cannot be empty, must
+// have at least one new member).
+//
+// (Since class names need to be known to implement these methods this cannot be
+// part of the base |RTCStats|. While these methods could be implemented using
+// templates, that would only work for immediate subclasses. Subclasses of
+// subclasses also have to override these methods, resulting in boilerplate
+// code. Using a macro avoids this and works for any |RTCStats| class, including
+// grandchildren.)
+//
+// Sample usage:
+//
+// rtcfoostats.h:
+// class RTCFooStats : public RTCStats {
+// public:
+// RTCFooStats(const std::string& id, double timestamp)
+// : RTCStats(id, timestamp),
+// foo("foo"),
+// bar("bar") {
+// }
+//
+// WEBRTC_RTCSTATS_IMPL(RTCStats, RTCFooStats,
+// &foo,
+// &bar);
+//
+// RTCStatsMember<int32_t> foo;
+// RTCStatsMember<int32_t> bar;
+// };
+//
+// rtcfoostats.cc:
+// const char RTCFooStats::kType[] = "foo-stats";
+//
+#define WEBRTC_RTCSTATS_IMPL(parent_class, this_class, ...) \
+ public: \
+ static const char kType[]; \
+ std::unique_ptr<webrtc::RTCStats> copy() const override { \
+ return std::unique_ptr<webrtc::RTCStats>(new this_class(*this)); \
+ } \
+ const char* type() const override { return this_class::kType; } \
+ protected: \
+ std::vector<const webrtc::RTCStatsMemberInterface*> \
+ MembersOfThisObjectAndAncestors( \
+ size_t local_var_additional_capacity) const override { \
+ const webrtc::RTCStatsMemberInterface* local_var_members[] = { \
+ __VA_ARGS__ \
+ }; \
+ size_t local_var_members_count = \
+ sizeof(local_var_members) / sizeof(local_var_members[0]); \
+ std::vector<const webrtc::RTCStatsMemberInterface*> local_var_members_vec =\
+ parent_class::MembersOfThisObjectAndAncestors( \
+ local_var_members_count + local_var_additional_capacity); \
+ RTC_DCHECK_GE( \
+ local_var_members_vec.capacity() - local_var_members_vec.size(), \
+ local_var_members_count + local_var_additional_capacity); \
+ local_var_members_vec.insert(local_var_members_vec.end(), \
+ &local_var_members[0], \
+ &local_var_members[local_var_members_count]); \
+ return local_var_members_vec; \
+ } \
+ public:
+
+// Interface for |RTCStats| members, which have a name and a value of a type
+// defined in a subclass. Only the types listed in |Type| are supported, these
+// are implemented by |RTCStatsMember<T>|. The value of a member may be
+// undefined, the value can only be read if |is_defined|.
+class RTCStatsMemberInterface {
+ public:
+ // Member value types.
+ enum Type {
+ kInt32, // int32_t
+ kUint32, // uint32_t
+ kInt64, // int64_t
+ kUint64, // uint64_t
+ kDouble, // double
+ kStaticString, // const char*
+ kString, // std::string
+
+ kSequenceInt32, // std::vector<int32_t>
+ kSequenceUint32, // std::vector<uint32_t>
+ kSequenceInt64, // std::vector<int64_t>
+ kSequenceUint64, // std::vector<uint64_t>
+ kSequenceDouble, // std::vector<double>
+ kSequenceStaticString, // std::vector<const char*>
+ kSequenceString, // std::vector<std::string>
+ };
+
+ virtual ~RTCStatsMemberInterface() {}
+
+ const char* name() const { return name_; }
+ virtual Type type() const = 0;
+ virtual bool is_sequence() const = 0;
+ virtual bool is_string() const = 0;
+ bool is_defined() const { return is_defined_; }
+ virtual std::string ValueToString() const = 0;
+
+ template<typename T>
+ const T& cast_to() const {
+ RTC_DCHECK_EQ(type(), T::kType);
+ return static_cast<const T&>(*this);
+ }
+
+ protected:
+ RTCStatsMemberInterface(const char* name, bool is_defined)
+ : name_(name), is_defined_(is_defined) {}
+
+ const char* const name_;
+ bool is_defined_;
+};
+
+// Template implementation of |RTCStatsMemberInterface|. Every possible |T| is
+// specialized in rtcstats.cc, using a different |T| results in a linker error
+// (undefined reference to |kType|). The supported types are the ones described
+// by |RTCStatsMemberInterface::Type|.
+template<typename T>
+class RTCStatsMember : public RTCStatsMemberInterface {
+ public:
+ static const Type kType;
+
+ explicit RTCStatsMember(const char* name)
+ : RTCStatsMemberInterface(name, false),
+ value_() {}
+ RTCStatsMember(const char* name, const T& value)
+ : RTCStatsMemberInterface(name, true),
+ value_(value) {}
+ RTCStatsMember(const char* name, T&& value)
+ : RTCStatsMemberInterface(name, true),
+ value_(std::move(value)) {}
+ explicit RTCStatsMember(const RTCStatsMember<T>& other)
+ : RTCStatsMemberInterface(other.name_, other.is_defined_),
+ value_(other.value_) {}
+ explicit RTCStatsMember(RTCStatsMember<T>&& other)
+ : RTCStatsMemberInterface(other.name_, other.is_defined_),
+ value_(std::move(other.value_)) {}
+
+ Type type() const override { return kType; }
+ bool is_sequence() const override;
+ bool is_string() const override;
+ std::string ValueToString() const override;
+
+ // Assignment operators.
+ T& operator=(const T& value) {
+ value_ = value;
+ is_defined_ = true;
+ return value_;
+ }
+ T& operator=(const T&& value) {
+ value_ = std::move(value);
+ is_defined_ = true;
+ return value_;
+ }
+ T& operator=(const RTCStatsMember<T>& other) {
+ RTC_DCHECK(other.is_defined_);
+ value_ = other.is_defined_;
+ is_defined_ = true;
+ return value_;
+ }
+
+ // Value getters.
+ T& operator*() {
+ RTC_DCHECK(is_defined_);
+ return value_;
+ }
+ const T& operator*() const {
+ RTC_DCHECK(is_defined_);
+ return value_;
+ }
+
+ // Value getters, arrow operator.
+ T* operator->() {
+ RTC_DCHECK(is_defined_);
+ return &value_;
+ }
+ const T* operator->() const {
+ RTC_DCHECK(is_defined_);
+ return &value_;
+ }
+
+ private:
+ T value_;
+};
+
+} // namespace webrtc
+
+#endif // WEBRTC_API_RTCSTATS_H_
diff --git a/webrtc/api/rtcstatsreport.h b/webrtc/api/rtcstatsreport.h
new file mode 100644
index 0000000..42237eb
--- /dev/null
+++ b/webrtc/api/rtcstatsreport.h
@@ -0,0 +1,86 @@
+/*
+ * Copyright 2016 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.
+ */
+
+#ifndef WEBRTC_API_RTCSTATSREPORT_H_
+#define WEBRTC_API_RTCSTATSREPORT_H_
+
+#include <map>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "webrtc/api/rtcstats.h"
+#include "webrtc/base/refcount.h"
+#include "webrtc/base/scoped_ref_ptr.h"
+
+namespace webrtc {
+
+// A collection of stats.
+// This is accessible as a map from |RTCStats::id| to |RTCStats|.
+class RTCStatsReport : public rtc::RefCountInterface {
+ public:
+ typedef std::map<std::string, std::unique_ptr<const RTCStats>> StatsMap;
+
+ class ConstIterator {
+ public:
+ ConstIterator(const ConstIterator&& other);
+ ~ConstIterator();
+
+ ConstIterator& operator++();
+ ConstIterator& operator++(int);
+ const RTCStats& operator*() const;
+ bool operator==(const ConstIterator& other) const;
+ bool operator!=(const ConstIterator& other) const;
+
+ private:
+ friend class RTCStatsReport;
+ ConstIterator(const rtc::scoped_refptr<const RTCStatsReport>& report,
+ StatsMap::const_iterator it);
+
+ // Reference report to make sure it is kept alive.
+ rtc::scoped_refptr<const RTCStatsReport> report_;
+ StatsMap::const_iterator it_;
+ };
+
+ static rtc::scoped_refptr<RTCStatsReport> Create();
+
+ RTCStatsReport();
+ RTCStatsReport(const RTCStatsReport& other) = delete;
+
+ bool AddStats(std::unique_ptr<const RTCStats> stats);
+ const RTCStats* operator[](const std::string& id) const;
+ size_t size() const { return stats_.size(); }
+
+ ConstIterator begin() const;
+ ConstIterator end() const;
+
+ // Gets the subset of stats that are of type |T|, where |T| is any class
+ // descending from |RTCStats|.
+ template<typename T>
+ std::vector<const T*> GetStatsOfType() const {
+ std::vector<const T*> stats_of_type;
+ for (const RTCStats& stats : *this) {
+ if (stats.type() == T::kType)
+ stats_of_type.push_back(&stats.cast_to<const T>());
+ }
+ return stats_of_type;
+ }
+
+ friend class rtc::RefCountedObject<RTCStatsReport>;
+
+ private:
+ ~RTCStatsReport() override;
+
+ StatsMap stats_;
+};
+
+} // namespace webrtc
+
+#endif // WEBRTC_API_RTCSTATSREPORT_H_