stats: add symbol table for future stat name encoding

include/envoy/stats/BUILD

@@ -14,6 +14,11 @@ envoy_cc_library(
     deps = ["//include/envoy/common:interval_set_interface"],
 )
 
+envoy_cc_library(
+    name = "symbol_table_interface",
+    hdrs = ["symbol_table.h"],
+)
+
 envoy_cc_library(
     name = "timespan",
     hdrs = ["timespan.h"],

include/envoy/stats/symbol_table.h

@@ -0,0 +1,51 @@
+#pragma once
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "envoy/common/pure.h"
+
+namespace Envoy {
+namespace Stats {
+
+using Symbol = uint32_t;
+using SymbolVec = std::vector<Symbol>;
+
+/**
+ * Interface for storing a stat name, which is a wrapper around a SymbolVec.
+ */
+class StatName {
+public:
+  StatName() {}
+  virtual ~StatName(){};
+  virtual std::string toString() const PURE;
+};
+
+using StatNamePtr = std::unique_ptr<StatName>;
+
+/**
+ * Interface for shortening and retrieving stat names.
+ *
+ * Guarantees that x = encode(x).toString() for any x.
+ */
+class SymbolTable {
+public:
+  virtual ~SymbolTable() {}
+
+  /**
+   * Encodes a stat name into a StatNamePtr. Expects the name to be period-delimited.
+   *
+   * @param name the stat name to encode.
+   * @return StatNamePtr a unique_ptr to the StatName class encapsulating the symbol vector.
+   */
+  virtual StatNamePtr encode(const std::string& name) PURE;
+
+  /**
+   * Returns the size of a SymbolTable, as measured in number of symbols stored.
+   */
+  virtual size_t size() const PURE;
+};
+
+} // namespace Stats
+} // namespace Envoy

source/common/stats/BUILD

@@ -17,6 +17,7 @@ envoy_cc_library(
         "libcircllhist",
     ],
     deps = [
+        ":symbol_table_lib",
         "//include/envoy/common:time_interface",
         "//include/envoy/server:options_interface",
         "//include/envoy/stats:stats_interface",
@@ -33,6 +34,17 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "symbol_table_lib",
+    srcs = ["symbol_table_impl.cc"],
+    hdrs = ["symbol_table_impl.h"],
+    external_deps = ["abseil_base"],
+    deps = [
+        "//include/envoy/stats:symbol_table_interface",
+        "//source/common/common:assert_lib",
+    ],
+)
+
 envoy_cc_library(
     name = "thread_local_store_lib",
     srcs = ["thread_local_store.cc"],

source/common/stats/symbol_table_impl.cc

@@ -0,0 +1,79 @@
+#include "common/stats/symbol_table_impl.h"
+
+#include <memory>
+#include <unordered_map>
+#include <vector>
+
+#include "common/common/assert.h"
+
+namespace Envoy {
+namespace Stats {
+
+// TODO(ambuc): There is a possible performance optimization here for avoiding the encoding of IPs,
+// if they appear in stat names. We don't want to waste time symbolizing an integer as an integer,
+// if we can help it.
+StatNamePtr SymbolTableImpl::encode(const std::string& name) {
+  SymbolVec symbol_vec;
+  std::vector<std::string> name_vec = absl::StrSplit(name, '.');
+  symbol_vec.reserve(name_vec.size());
+  std::transform(name_vec.begin(), name_vec.end(), std::back_inserter(symbol_vec),
+                 [this](std::string x) { return toSymbol(x); });
+
+  return std::make_unique<StatNameImpl>(symbol_vec, this);
+}
+
+std::string SymbolTableImpl::decode(const SymbolVec& symbol_vec) const {
+  std::vector<std::string> name;
+  name.reserve(symbol_vec.size());
+  std::transform(symbol_vec.begin(), symbol_vec.end(), std::back_inserter(name),
+                 [this](Symbol x) { return fromSymbol(x); });
+  return absl::StrJoin(name, ".");
+}
+
+void SymbolTableImpl::free(const SymbolVec& symbol_vec) {
+  for (const Symbol symbol : symbol_vec) {
+    auto decode_search = decode_map_.find(symbol);
+    RELEASE_ASSERT(decode_search != decode_map_.end(), "");
+
+    const std::string& str = decode_search->second;
+    auto encode_search = encode_map_.find(str);
+    RELEASE_ASSERT(encode_search != encode_map_.end(), "");
+
+    ((encode_search->second).second)--;
+    // If that was the last remaining client usage of the symbol, erase the the current
+    // mappings and add the now-unused symbol to the reuse pool.
+    if ((encode_search->second).second == 0) {
+      decode_map_.erase(decode_search);
+      encode_map_.erase(encode_search);
+      pool_.push_back(symbol);
+    }
+  }
+}
+
+Symbol SymbolTableImpl::toSymbol(const std::string& str) {
+  Symbol result;
+  auto encode_insert = encode_map_.insert({str, std::make_pair(current_symbol_, 1)});
+  // If the insertion took place, we mirror the insertion in the decode_map.
+  if (encode_insert.second) {
+    auto decode_insert = decode_map_.insert({current_symbol_, str});
+    // We expect the decode_map to be in lockstep.
+    RELEASE_ASSERT(decode_insert.second, "");
+    result = current_symbol_;
+    newSymbol();
+  } else {
+    // If the insertion didn't take place, return the actual value at that location
+    result = (encode_insert.first)->second.first;
+    // and up the refcount at that location
+    ++(encode_insert.first)->second.second;
+  }
+  return result;
+}
+
+std::string SymbolTableImpl::fromSymbol(const Symbol symbol) const {
+  auto search = decode_map_.find(symbol);
+  RELEASE_ASSERT(search != decode_map_.end(), "");
+  return search->second;
+}
+
+} // namespace Stats
+} // namespace Envoy

source/common/stats/symbol_table_impl.h

@@ -0,0 +1,122 @@
+#pragma once
+
+#include <algorithm>
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "envoy/common/exception.h"
+#include "envoy/stats/symbol_table.h"
+
+#include "common/common/assert.h"
+
+#include "absl/strings/str_join.h"
+#include "absl/strings/str_split.h"
+
+namespace Envoy {
+namespace Stats {
+
+/**
+ * Underlying SymbolTableImpl implementation which assists with per-symbol reference counting.
+ *
+ * The underlying Symbol / SymbolVec data structures are not meant for public consumption. One side
+ * effect of the non-monotonically-increasing symbol counter is that if a string is encoded, the
+ * resulting stat is destroyed, and then that same string is re-encoded, it may or may not encode to
+ * the same underlying symbol.
+ */
+class SymbolTableImpl : public SymbolTable {
+public:
+  StatNamePtr encode(const std::string& name) override;
+
+  // For testing purposes only.
+  size_t size() const override {
+    RELEASE_ASSERT(encode_map_.size() == decode_map_.size(), "");
+    return encode_map_.size();
+  }
+
+private:
+  friend class StatNameImpl;
+  friend class StatNameTest;
+  /**
+   * Decodes a vector of symbols back into its period-delimited stat name.
+   * If decoding fails on any part of the symbol_vec, we release_assert and crash hard, since this
+   * should never happen, and we don't want to continue running with a corrupt stats set.
+   *
+   * @param symbol_vec the vector of symbols to decode.
+   * @return std::string the retrieved stat name.
+   */
+  std::string decode(const SymbolVec& symbol_vec) const;
+
+  /**
+   * Since SymbolTableImpl does manual reference counting, a client of SymbolTable (such as
+   * StatName) must manually call free(symbol_vec) when it is freeing the stat it represents. This
+   * way, the symbol table will grow and shrink dynamically, instead of being write-only.
+   *
+   * @param SymbolVec& the vector of symbols to be freed.
+   * @return bool whether or not the total free operation was successful. Expected to be true.
+   */
+  void free(const SymbolVec& symbol_vec);
+
+  /**
+   * Convenience function for encode(), symbolizing one string segment at a time.
+   *
+   * @param std::string& the individual string to be encoded as a symbol.
+   * @return Symbol the encoded string.
+   */
+  Symbol toSymbol(const std::string& str);
+
+  /**
+   * Convenience function for decode(), decoding one symbol at a time.
+   *
+   * @param Symbol the individual symbol to be decoded.
+   * @return std::string the decoded string.
+   */
+  std::string fromSymbol(const Symbol symbol) const;
+
+  // Stages a new symbol for use. To be called after a successful insertion.
+  void newSymbol() {
+    if (pool_.empty()) {
+      RELEASE_ASSERT(monotonic_counter_ < std::numeric_limits<Symbol>::max(), "");
+      current_symbol_ = ++monotonic_counter_;
+    } else {
+      current_symbol_ = pool_.front();
+      pool_.pop_front();
+    }
+  }
+
+  // Stores the symbol to be used at next insertion. This should exist ahead of insertion time so
+  // that if insertion succeeds, the value written is the correct one.
+  Symbol current_symbol_{};
+
+  // If the free pool is exhausted, we monotonically increase this counter.
+  Symbol monotonic_counter_{};
+
+  // Bimap implementation.
+  // The encode map stores both the symbol and the ref count of that symbol.
+  std::unordered_map<std::string, std::pair<Symbol, uint32_t>> encode_map_;
+  std::unordered_map<Symbol, std::string> decode_map_;
+
+  // Free pool of symbols for re-use.
+  std::deque<Symbol> pool_;
+};
+
+/**
+ * Implements RAII for Symbols, since the StatName destructor does the work of freeing its component
+ * symbols.
+ */
+class StatNameImpl : public StatName {
+public:
+  StatNameImpl(SymbolVec symbol_vec, SymbolTableImpl* symbol_table)
+      : symbol_vec_(symbol_vec), symbol_table_(symbol_table) {}
+  ~StatNameImpl() override { symbol_table_->free(symbol_vec_); }
+  std::string toString() const override { return symbol_table_->decode(symbol_vec_); }
+
+private:
+  friend class StatNameTest;
+  SymbolVec symbol_vec_;
+  SymbolTableImpl* symbol_table_;
+};
+
+} // namespace Stats
+} // namespace Envoy

test/common/stats/BUILD

@@ -21,10 +21,22 @@ envoy_cc_test(
     ],
 )
 
+envoy_cc_test(
+    name = "symbol_table_test",
+    srcs = ["symbol_table_test.cc"],
+    deps = [
+        "//source/common/stats:symbol_table_lib",
+        "//test/mocks/stats:stats_mocks",
+        "//test/test_common:logging_lib",
+        "//test/test_common:utility_lib",
+    ],
+)
+
 envoy_cc_test(
     name = "thread_local_store_test",
     srcs = ["thread_local_store_test.cc"],
     deps = [
+        "//source/common/stats:symbol_table_lib",
         "//source/common/stats:thread_local_store_lib",
         "//test/mocks/event:event_mocks",
         "//test/mocks/server:server_mocks",