RTCStats and RTCStatsReport added (webrtc/stats)

webrtc/api/rtcstats.h

+/*
+ *  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* const kType;
+// The address of |kType| is used as a unique class identifier and the value as
+// 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 address of the static |kType| variable of the implementing
+  // class. Comparing it to |&T::kType| tests if a stats object is of type |T|.
+  virtual const char* const* type() const = 0;
+  // Returns the value of the static |kType| variable of the implementing class.
+  virtual const char* type_name() 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>
+  T& cast_to() {
+    RTC_DCHECK_EQ(type(), &T::kType);
+    return static_cast<T&>(*this);
+  }
+  template<typename T>
+  T& cast_to() const {
+    RTC_DCHECK_EQ(type(), &T::kType);
+    return static_cast<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*> ThisMembers(
+      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.

[hta-webrtc, 2016/08/22 07:01:53]

The macro starts with "public", so it doesn't have to be in a public section -
what about

"All |RTCStats| subclasses must use this macro. It declares public class
members, so should be in the public section of the declaration."

[hbos, 2016/08/22 15:17:36]

But the macro changes the protection level (? -> public -> protected -> public).
It would be confusing if the macro was used anywhere but the public section
since it would otherwise "sneakingly" change the protection level to public. I
think it should be required to be in the pubic section, macros shouldn't be used
to change protection level.

+//
+// This macro declares the static |kType| and overrides methods as required by
+// subclasses of |RTCStats|: |copy|, |type|, |type_name| and |ThisMembers|.
+// 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(RTCFooStats, RTCStats,
+//         &foo,
+//         &bar);
+//
+//     RTCStatsMember<int32_t> foo;
+//     RTCStatsMember<int32_t> bar;
+//   };
+//
+// rtcfoostats.cc:
+//   const char* const RTCFooStats::kType = "foo-stats";
+//
+#define WEBRTC_RTCSTATS_IMPL(this_class, parent_class, ...)                    \

[hta-webrtc, 2016/08/22 07:01:53]

Argh. This is a macro, and it's a macro in an .h file.

Since this macro is used in defining the objects on the public API of the class,
I don't see a way to hide it. Can you ask nisse to take a look? (I believe he
knows a bit of C++...)

[hbos, 2016/08/22 15:17:36]

I'll ask nisse to take a look.

+ public:                                                                       \
+  static const char* const kType;                                              \
+  std::unique_ptr<webrtc::RTCStats> copy() const override {                    \
+    return std::unique_ptr<webrtc::RTCStats>(new this_class(*this));           \
+  }                                                                            \
+  const char* const* type() const override { return &this_class::kType; }      \

[hta-webrtc, 2016/08/22 07:01:53]

Is it possible to use "typeof(this)" or some such construct to avoid the
ugliness of having to pass the class name to a macro that can only be used
inside the class definition?

[hbos, 2016/08/22 15:17:36]

Hmm.. I don't think that is possible, and we don't compile with RTTI (typeid)
and neither that or decltype can be used to reach static member variables AFAIK.

+  const char* type_name() const override { return this_class::kType; }         \
+ protected:                                                                    \
+  std::vector<const webrtc::RTCStatsMemberInterface*> ThisMembers(             \

[hta-webrtc, 2016/08/22 07:01:53]

ThisMembers is such an ugly name. What about MembersOfThisObjectAndAncestors?

[hbos, 2016/08/22 15:17:36]

Done.

+      size_t additional_capacity) const override {                             \
+    const webrtc::RTCStatsMemberInterface* members[] = {                       \
+      __VA_ARGS__                                                              \
+    };                                                                         \
+    size_t members_count = sizeof(members) / sizeof(members[0]);               \
+    std::vector<const webrtc::RTCStatsMemberInterface*> members_vec =          \
+        parent_class::ThisMembers(additional_capacity + members_count);        \
+    members_vec.insert(members_vec.end(),                                      \
+                       &members[0], &members[members_count]);                  \
+    return members_vec;                                                        \
+  }                                                                            \
+ public:
+
+// Interface for |RTCStats| members, which have a name and an optional value.

[hta-webrtc, 2016/08/22 07:01:53]

Value type, not value?
I don't think "optional" is the right word here. "and a value of a type defined
in a subclass" is more correct.

[hbos, 2016/08/22 15:17:36]

Updated comment. (By optional I meant that the value can be defined or
undefined.)

+// The value type is implementation-specific. Only the types listed in |Type|
+// are supported, these are implemented by |RTCStatsMember<T>|.
+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;  // true for sequences of strings too.
+  bool is_defined() const { return is_defined_; }
+  virtual std::string ValueToString() const = 0;
+
+  template<typename T>
+  T& cast_to() const {
+    RTC_DCHECK_EQ(type(), T::kType);
+    return static_cast<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_