Introduce the opencensus::tags namespace. (#192)

- Move stats::TagKey and stats::TagSet (renamed to TagMap) to tags::
- Add compatibility shims with deprecation warning.

This commit does not change the API.

Author: g-easy

opencensus/stats/BUILD

@@ -67,8 +67,6 @@ cc_library(
         "internal/set_aggregation_window.cc",
         "internal/stats_exporter.cc",
         "internal/stats_manager.cc",
-        "internal/tag_key.cc",
-        "internal/tag_set.cc",
         "internal/view.cc",
         "internal/view_data.cc",
         "internal/view_data_impl.cc",
@@ -98,9 +96,9 @@ cc_library(
     ],
     copts = DEFAULT_COPTS,
     deps = [
-        "//opencensus/common/internal:hash_mix",
         "//opencensus/common/internal:stats_object",
         "//opencensus/common/internal:string_vector_hash",
+        "//opencensus/tags",
         "@com_google_absl//absl/base:core_headers",
         "@com_google_absl//absl/memory",
         "@com_google_absl//absl/strings",
@@ -208,28 +206,6 @@ cc_test(
     ],
 )
 
-cc_test(
-    name = "tag_key_test",
-    size = "small",
-    srcs = ["internal/tag_key_test.cc"],
-    copts = TEST_COPTS,
-    deps = [
-        ":core",
-        "@com_google_googletest//:gtest_main",
-    ],
-)
-
-cc_test(
-    name = "tag_set_test",
-    size = "small",
-    srcs = ["internal/tag_set_test.cc"],
-    copts = TEST_COPTS,
-    deps = [
-        ":core",
-        "@com_google_googletest//:gtest_main",
-    ],
-)
-
 cc_test(
     name = "view_data_impl_test",
     srcs = ["internal/view_data_impl_test.cc"],

opencensus/stats/tag_key.h

@@ -15,38 +15,16 @@
 #ifndef OPENCENSUS_STATS_TAG_KEY_H_
 #define OPENCENSUS_STATS_TAG_KEY_H_
 
-#include <cstddef>
-#include <cstdint>
-#include <string>
-
-#include "absl/strings/string_view.h"
+#include "absl/base/macros.h"
+#include "opencensus/tags/tag_key.h"
 
 namespace opencensus {
 namespace stats {
 
-// TagKey is a lightweight, immutable representation of a tag key. It has a
-// trivial destructor and can be safely used as a local static variable.
-class TagKey final {
- public:
-  // Registers a tag key with 'name'. Registering the same name twice produces
-  // equal TagKeys.
-  static TagKey Register(absl::string_view name);
-
-  const std::string& name() const;
-
-  bool operator==(TagKey other) const { return id_ == other.id_; }
-  bool operator!=(TagKey other) const { return id_ != other.id_; }
-  bool operator<(TagKey other) const { return id_ < other.id_; }
-
-  // Returns a suitable hash of the TagKey. The implementation may change.
-  std::size_t hash() const { return id_; }
-
- private:
-  friend class TagKeyRegistry;
-  explicit TagKey(uint64_t id) : id_(id) {}
-
-  uint64_t id_;
-};
+ABSL_DEPRECATED(
+    "TagKey has moved to opencensus::tags. This is a compatibility "
+    "shim and will be removed on or after 2019-03-20")
+typedef opencensus::tags::TagKey TagKey;
 
 }  // namespace stats
 }  // namespace opencensus

opencensus/stats/tag_set.h

@@ -15,55 +15,16 @@
 #ifndef OPENCENSUS_STATS_TAG_SET_H_
 #define OPENCENSUS_STATS_TAG_SET_H_
 
-#include <initializer_list>
-#include <string>
-#include <utility>
-#include <vector>
-
-#include "absl/strings/string_view.h"
-#include "opencensus/stats/tag_key.h"
+#include "absl/base/macros.h"
+#include "opencensus/tags/tag_map.h"
 
 namespace opencensus {
 namespace stats {
 
-// TagSet represents a set of key-value tags, and provides efficient equality
-// and hash operations. A TagSet is expensive to construct, and should be shared
-// between uses where possible.
-// TagSet is immutable.
-class TagSet final {
- public:
-  // Both constructors are not explicit so that Record({}, {{"k", "v"}}) works.
-  // This constructor is needed because even though we copy to a vector
-  // internally because c++ cannot deduce the conversion needed.
-  TagSet(std::initializer_list<std::pair<TagKey, absl::string_view>> tags);
-  // This constructor is needed so that callers can dynamically construct
-  // tagsets. It takes the argument by value to allow it to be moved.
-  TagSet(std::vector<std::pair<TagKey, std::string>> tags);
-
-  // Accesses the tags sorted by key (in an implementation-defined, not
-  // lexicographic, order).
-  const std::vector<std::pair<TagKey, std::string>>& tags() const {
-    return tags_;
-  }
-
-  struct Hash {
-    std::size_t operator()(const TagSet& tag_set) const;
-  };
-
-  bool operator==(const TagSet& other) const;
-  bool operator!=(const TagSet& other) const { return !(*this == other); }
-
-  // Returns a human-readable string for debugging. Do not rely on its format or
-  // try to parse it. Do not use it to retrieve tags.
-  std::string DebugString() const;
-
- private:
-  void Initialize();
-
-  std::size_t hash_;
-  // TODO: add an option to store string_views to avoid copies.
-  std::vector<std::pair<TagKey, std::string>> tags_;
-};
+ABSL_DEPRECATED(
+    "TagSet has moved to opencensus::tags::TagMap. This is a "
+    "compatibility shim and will be removed on or after 2019-03-20")
+typedef opencensus::tags::TagMap TagSet;
 
 }  // namespace stats
 }  // namespace opencensus

opencensus/tags/BUILD

@@ -0,0 +1,65 @@
+# OpenCensus C++ Tags library.
+#
+# Copyright 2018, OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("//opencensus:copts.bzl", "DEFAULT_COPTS", "TEST_COPTS")
+
+licenses(["notice"])  # Apache License 2.0
+
+package(default_visibility = ["//visibility:private"])
+
+# The public tags API.
+cc_library(
+    name = "tags",
+    hdrs = [
+      "tag_map.h",
+      "tag_key.h",
+    ],
+    srcs = [
+      "internal/tag_key.cc",
+      "internal/tag_map.cc",
+    ],
+    copts = DEFAULT_COPTS,
+    visibility = ["//visibility:public"],
+    deps = [
+        "//opencensus/common/internal:hash_mix",
+        "@com_google_absl//absl/base:core_headers",
+        "@com_google_absl//absl/strings",
+        "@com_google_absl//absl/synchronization",
+    ],
+)
+
+# Tests
+# ========================================================================= #
+
+cc_test(
+    name = "tag_key_test",
+    srcs = ["internal/tag_key_test.cc"],
+    copts = TEST_COPTS,
+    deps = [
+        ":tags",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "tag_map_test",
+    srcs = ["internal/tag_map_test.cc"],
+    copts = TEST_COPTS,
+    deps = [
+        ":tags",
+        "@com_google_googletest//:gtest_main",
+    ],
+)

opencensus/stats/internal/tag_key.cc opencensus/tags/internal/tag_key.ccopencensus/stats/internal/tag_key.cc renamed to opencensus/tags/internal/tag_key.cc

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#include "opencensus/stats/tag_key.h"
+#include "opencensus/tags/tag_key.h"
 
 #include <cstdint>
 #include <string>
@@ -23,18 +23,18 @@
 #include "absl/synchronization/mutex.h"
 
 namespace opencensus {
-namespace stats {
+namespace tags {
 
-class TagKeyRegistry final {
+class TagKeyRegistry {
  public:
   static TagKeyRegistry* Get() {
-    static TagKeyRegistry* global_tag_key_registry = new TagKeyRegistry();
+    static TagKeyRegistry* global_tag_key_registry = new TagKeyRegistry;
     return global_tag_key_registry;
   }
 
-  TagKey Register(absl::string_view name);
+  TagKey Register(absl::string_view name) LOCKS_EXCLUDED(mu_);
 
-  const std::string& TagKeyName(TagKey key) const {
+  const std::string& TagKeyName(TagKey key) const LOCKS_EXCLUDED(mu_) {
     absl::ReaderMutexLock l(&mu_);
     return registered_tag_keys_[key.id_];
   }
@@ -69,5 +69,5 @@ const std::string& TagKey::name() const {
   return TagKeyRegistry::Get()->TagKeyName(*this);
 }
 
-}  // namespace stats
+}  // namespace tags
 }  // namespace opencensus

opencensus/stats/internal/tag_key_test.cc opencensus/tags/internal/tag_key_test.ccopencensus/stats/internal/tag_key_test.cc renamed to opencensus/tags/internal/tag_key_test.cc

@@ -12,12 +12,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#include "opencensus/stats/tag_key.h"
+#include "opencensus/tags/tag_key.h"
 
 #include "gtest/gtest.h"
 
 namespace opencensus {
-namespace stats {
+namespace tags {
 namespace {
 
 TEST(TagKeyTest, Name) {
@@ -40,5 +40,5 @@ TEST(TagKeyTest, Inequality) {
 }
 
 }  // namespace
-}  // namespace stats
+}  // namespace tags
 }  // namespace opencensus

opencensus/stats/internal/tag_set.cc opencensus/tags/internal/tag_map.ccopencensus/stats/internal/tag_set.cc renamed to opencensus/tags/internal/tag_map.cc

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#include "opencensus/stats/tag_set.h"
+#include "opencensus/tags/tag_map.h"
 
 #include <functional>
 #include <initializer_list>
@@ -24,12 +24,12 @@
 #include "absl/strings/str_join.h"
 #include "absl/strings/string_view.h"
 #include "opencensus/common/internal/hash_mix.h"
-#include "opencensus/stats/tag_key.h"
+#include "opencensus/tags/tag_key.h"
 
 namespace opencensus {
-namespace stats {
+namespace tags {
 
-TagSet::TagSet(
+TagMap::TagMap(
     std::initializer_list<std::pair<TagKey, absl::string_view>> tags) {
   tags_.reserve(tags.size());
   for (const auto& tag : tags) {
@@ -38,12 +38,12 @@ TagSet::TagSet(
   Initialize();
 }
 
-TagSet::TagSet(std::vector<std::pair<TagKey, std::string>> tags)
+TagMap::TagMap(std::vector<std::pair<TagKey, std::string>> tags)
     : tags_(std::move(tags)) {
   Initialize();
 }
 
-void TagSet::Initialize() {
+void TagMap::Initialize() {
   std::sort(tags_.begin(), tags_.end());
 
   std::hash<std::string> hasher;
@@ -55,15 +55,15 @@ void TagSet::Initialize() {
   hash_ = mixer.get();
 }
 
-std::size_t TagSet::Hash::operator()(const TagSet& tag_set) const {
-  return tag_set.hash_;
+std::size_t TagMap::Hash::operator()(const TagMap& tags) const {
+  return tags.hash_;
 }
 
-bool TagSet::operator==(const TagSet& other) const {
+bool TagMap::operator==(const TagMap& other) const {
   return tags_ == other.tags_;
 }
 
-std::string TagSet::DebugString() const {
+std::string TagMap::DebugString() const {
   return absl::StrCat(
       "{",
       absl::StrJoin(
@@ -75,5 +75,5 @@ std::string TagSet::DebugString() const {
       "}");
 }
 
-}  // namespace stats
+}  // namespace tags
 }  // namespace opencensus