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
+// http://rawgit.com/w3c/webrtc-stats/master/webrtc-stats.html.

[hta - Chromium, 2016/08/15 15:14:57]

Please use the w3c.github.io link - it's not as up to date, but it's less likely
to be in a broken state. (At the moment at least.)

[hbos, 2016/08/15 22:46:43]

Done.

+//
+// 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
+// http://rawgit.com/w3c/webrtc-stats/master/webrtc-stats.html#rtcstatstype-str*.
+//
+// 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());

[hta - Chromium, 2016/08/15 15:14:57]

Even examples in comments should follow the style guide ... use braces.

[hbos, 2016/08/15 22:46:43]

Done.

+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 in milliseconds relative to the UNIX epoch (Jan 1, 1970, UTC).

[hta - Chromium, 2016/08/15 15:14:56]

Please use seconds when the type is double, unless you have a VERY powerful
precedent for not doing so. The advantage of using a floating-point type is that
scale doesn't matter.

Also delete the word "milliseconds" - doubles have a lot more precision than
that.

[hbos, 2016/08/15 22:46:43]

Done. Now I say that it is in seconds, without - I hope - implying that it is in
whole seconds (integers).

+  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.
+  virtual std::vector<const RTCStatsMemberInterface*> Members() const = 0;
+
+  std::string ToString() const;

[hta - Chromium, 2016/08/15 15:14:57]

What representation does ToString() return? Is it useful for display only, or is
it supposed to parse as legal JSON?

[hbos, 2016/08/15 22:46:43]

Creates a string like so:

peer-connection {
  id: "peerConnectionId"
  timestamp: 0.0
  dataChannelsOpened: 1
  dataChannelsClosed: 0
}

Useful for debugging.

+
+  template<typename T>
+  T& to() const {

[hta - Chromium, 2016/08/15 15:14:57]

Is this function intended for downcasts (from the base type to the subtype)? If
so, make a comment that it's so.

This is RTTI (run time type information), which most of the time is a bad
practice, so let's make sure we need it.

Should it be cast_to, or is to() in common usage?

[hbos, 2016/08/15 22:46:43]

Updated to cast_to.

Yes, downcasting, e.g. RTCStats -> RTCFooStats. This is for the case when you
want to inspect specific types of stats, meaning you already have the type and
members in mind. I think RTTI is the right approach for that. You wouldn't use
this for general handling of stats, such as if you want to loop through every
stat, you can do that with Members().

This allows filtering for RTCFooStats from a collection of RTCStats and then
reading the value of foo.x directly without having to first search for x amongst
a generic set of members. Casting yields cleaner code and compile-time errors if
you use wrong member name/type. The benefit of this over casting yourself is we
have a DCHECK.

+    RTC_DCHECK_EQ(type(), &T::kType);
+    return static_cast<T&>(*this);
+  }
+
+ protected:
+  static std::vector<const RTCStatsMemberInterface*> MembersVector(
+      const RTCStatsMemberInterface** members, size_t members_count);
+
+  std::string const id_;
+  double timestamp_;
+};
+
+// Interface for |RTCStats| members, which have a name and an optional value.
+// 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 has_value() const { return has_value_; }
+  virtual std::string ValueToString() const = 0;
+
+  template<typename T>
+  T& to() const {

[hta - Chromium, 2016/08/15 15:14:57]

Same comment about name of function.

[hbos, 2016/08/15 22:46:43]

Done.

+    RTC_DCHECK_EQ(type(), T::kType);
+    return static_cast<T&>(*this);
+  }
+
+ protected:
+  RTCStatsMemberInterface(const char* name, bool has_value)
+      : name_(name), has_value_(has_value) {}
+
+  const char* const name_;
+  bool has_value_;
+};
+
+// 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.has_value_),
+        value_(other.value_) {}
+  explicit RTCStatsMember(RTCStatsMember<T>&& other)
+      : RTCStatsMemberInterface(other.name_, other.has_value_),
+        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;
+    has_value_ = true;
+    return value_;
+  }
+  T& operator=(const T&& value) {
+    value_ = std::move(value);
+    has_value_ = true;
+    return value_;
+  }
+  T& operator=(const RTCStatsMember<T>& other) {
+    RTC_DCHECK(other.has_value_);
+    value_ = other.has_value_;
+    has_value_ = true;
+    return value_;
+  }
+
+  // Value getters.
+  T& operator*() {
+    RTC_DCHECK(has_value_);
+    return value_;
+  }
+  const T& operator*() const {
+    RTC_DCHECK(has_value_);
+    return value_;
+  }
+
+  // Value getters, arrow operator.
+  T* operator->() {
+    RTC_DCHECK(has_value_);
+    return &value_;
+  }
+  const T* operator->() const {
+    RTC_DCHECK(has_value_);
+    return &value_;
+  }
+
+ private:
+  T value_;
+};
+
+}  // namespace webrtc
+
+#endif  // WEBRTC_API_RTCSTATS_H_