Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <memory>
       4             : #include <string>
       5             : #include <vector>
       6             : 
       7             : #include "envoy/common/pure.h"
       8             : 
       9             : namespace Envoy {
      10             : namespace Stats {
      11             : 
      12             : class StatName;
      13             : 
      14             : class StatsMatcher {
      15             : public:
      16             :   // Holds the result of fastRejects(). This contains state that must be then
      17             :   // passed to slowRejects() for the final 2-phase determination of whether a
      18             :   // stat can be rejected.
      19             :   enum class FastResult {
      20             :     NoMatch,
      21             :     Rejects,
      22             :     Matches,
      23             :   };
      24             : 
      25         232 :   virtual ~StatsMatcher() = default;
      26             : 
      27             :   /**
      28             :    * Take a metric name and report whether or not it should be instantiated.
      29             :    * This may need to convert the StatName to a string. This is equivalent to
      30             :    * calling fastRejects() and then calling slowResults() if necessary.
      31             :    *
      32             :    * @param name the name of a Stats::Metric.
      33             :    * @return bool true if that stat should not be instantiated.
      34             :    */
      35             :   virtual bool rejects(StatName name) const PURE;
      36             : 
      37             :   /**
      38             :    * Takes a metric name and quickly determines whether it can be rejected based
      39             :    * purely on the StatName. If fastResults(stat_name).rejects() is 'false', we
      40             :    * will need to check slowRejects as well. It should not be necessary to cache
      41             :    * the result of fastRejects() -- it's cheap enough to recompute. However we
      42             :    * should protect slowRejects() by a cache due to its speed and the potential
      43             :    * need to take a symbol table lock.
      44             :    *
      45             :    * @param name the name of a Stats::Metric.
      46             :    * @return A result indicating whether the stat can be quickly rejected, as
      47             :    *         well as state that is then passed to slowRejects if rejection
      48             :    *         cannot be quickly determined.
      49             :    */
      50             :   virtual FastResult fastRejects(StatName name) const PURE;
      51             : 
      52             :   /**
      53             :    * Takes a metric name and converts it to a string, if needed, to determine
      54             :    * whether it needs to be rejected. This is intended to be used if
      55             :    * fastRejects() cannot determine an early rejection. It is a good idea to
      56             :    * cache the results of this, to avoid the stringification overhead, potential
      57             :    * regex overhead, plus a global symbol table lock.
      58             :    *
      59             :    * @param fast_result the result of fastRejects(), which must be called first.
      60             :    * @param name the name of a Stats::Metric.
      61             :    * @return bool true if that stat should not be instantiated.
      62             :    */
      63             :   virtual bool slowRejects(FastResult fast_result, StatName name) const PURE;
      64             : 
      65             :   /**
      66             :    * Helps determine whether the matcher needs to be called. This can be used
      67             :    * to short-circuit elaboration of stats names.
      68             :    *
      69             :    * @return bool whether StatsMatcher can be statically determined to accept
      70             :    *              all stats. It's possible to construct a matcher where
      71             :    *              acceptsAll() returns false, but rejects() is always false.
      72             :    */
      73             :   virtual bool acceptsAll() const PURE;
      74             : 
      75             :   /**
      76             :    * Helps determine whether the matcher needs to be called. This can be used
      77             :    * to short-circuit elaboration of stats names.
      78             :    *
      79             :    * @return bool whether StatsMatcher can be statically determined to reject
      80             :    *              all stats. It's possible to construct a matcher where
      81             :    *              rejectsAll() returns false, but rejects() is always true.
      82             :    */
      83             :   virtual bool rejectsAll() const PURE;
      84             : };
      85             : 
      86             : using StatsMatcherPtr = std::unique_ptr<const StatsMatcher>;
      87             : 
      88             : } // namespace Stats
      89             : } // namespace Envoy