legacy-libs/grpc-cloned/deps/grpc/src/core/ext/filters/client_channel/resolver.h

   1 /*
   2  *
   3  * Copyright 2015 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_H
  20 #define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include <grpc/impl/codegen/grpc_types.h>
  25
  26 #include "src/core/ext/filters/client_channel/server_address.h"
  27 #include "src/core/ext/filters/client_channel/service_config.h"
  28 #include "src/core/lib/gprpp/abstract.h"
  29 #include "src/core/lib/gprpp/orphanable.h"
  30 #include "src/core/lib/gprpp/ref_counted_ptr.h"
  31 #include "src/core/lib/iomgr/combiner.h"
  32 #include "src/core/lib/iomgr/iomgr.h"
  33
  34 extern grpc_core::DebugOnlyTraceFlag grpc_trace_resolver_refcount;
  35
  36 namespace grpc_core {
  37
  38 /// Interface for name resolution.
  39 ///
  40 /// This interface is designed to support both push-based and pull-based
  41 /// mechanisms.  A push-based mechanism is one where the resolver will
  42 /// subscribe to updates for a given name, and the name service will
  43 /// proactively send new data to the resolver whenever the data associated
  44 /// with the name changes.  A pull-based mechanism is one where the resolver
  45 /// needs to query the name service again to get updated information (e.g.,
  46 /// DNS).
  47 ///
  48 /// Note: All methods with a "Locked" suffix must be called from the
  49 /// combiner passed to the constructor.
  50 class Resolver : public InternallyRefCounted<Resolver> {
  51  public:
  52   /// Results returned by the resolver.
  53   struct Result {
  54     ServerAddressList addresses;
  55     RefCountedPtr<ServiceConfig> service_config;
  56     grpc_error* service_config_error = GRPC_ERROR_NONE;
  57     const grpc_channel_args* args = nullptr;
  58
  59     // TODO(roth): Remove everything below once grpc_error and
  60     // grpc_channel_args are convert to copyable and movable C++ objects.
  61     Result() = default;
  62     ~Result();
  63     Result(const Result& other);
  64     Result(Result&& other);
  65     Result& operator=(const Result& other);
  66     Result& operator=(Result&& other);
  67   };
  68
  69   /// A proxy object used by the resolver to return results to the
  70   /// client channel.
  71   class ResultHandler {
  72    public:
  73     virtual ~ResultHandler() {}
  74
  75     /// Returns a result to the channel.
  76     /// Takes ownership of \a result.args.
  77     virtual void ReturnResult(Result result) GRPC_ABSTRACT;  // NOLINT
  78
  79     /// Returns a transient error to the channel.
  80     /// If the resolver does not set the GRPC_ERROR_INT_GRPC_STATUS
  81     /// attribute on the error, calls will be failed with status UNKNOWN.
  82     virtual void ReturnError(grpc_error* error) GRPC_ABSTRACT;
  83
  84     // TODO(yashkt): As part of the service config error handling
  85     // changes, add a method to parse the service config JSON string.
  86
  87     GRPC_ABSTRACT_BASE_CLASS
  88   };
  89
  90   // Not copyable nor movable.
  91   Resolver(const Resolver&) = delete;
  92   Resolver& operator=(const Resolver&) = delete;
  93
  94   /// Starts resolving.
  95   virtual void StartLocked() GRPC_ABSTRACT;
  96
  97   /// Asks the resolver to obtain an updated resolver result, if
  98   /// applicable.
  99   ///
 100   /// This is useful for pull-based implementations to decide when to
 101   /// re-resolve.  However, the implementation is not required to
 102   /// re-resolve immediately upon receiving this call; it may instead
 103   /// elect to delay based on some configured minimum time between
 104   /// queries, to avoid hammering the name service with queries.
 105   ///
 106   /// For push-based implementations, this may be a no-op.
 107   ///
 108   /// Note: Implementations must not invoke any method on the
 109   /// ResultHandler from within this call.
 110   virtual void RequestReresolutionLocked() {}
 111
 112   /// Resets the re-resolution backoff, if any.
 113   /// This needs to be implemented only by pull-based implementations;
 114   /// for push-based implementations, it will be a no-op.
 115   /// TODO(roth): Pull the backoff code out of resolver and into
 116   /// client_channel, so that it can be shared across resolver
 117   /// implementations.  At that point, this method can go away.
 118   virtual void ResetBackoffLocked() {}
 119
 120   // Note: This must be invoked while holding the combiner.
 121   void Orphan() override {
 122     ShutdownLocked();
 123     Unref();
 124   }
 125
 126   GRPC_ABSTRACT_BASE_CLASS
 127
 128  protected:
 129   GRPC_ALLOW_CLASS_TO_USE_NON_PUBLIC_DELETE
 130
 131   /// Does NOT take ownership of the reference to \a combiner.
 132   // TODO(roth): Once we have a C++-like interface for combiners, this
 133   // API should change to take a RefCountedPtr<>, so that we always take
 134   // ownership of a new ref.
 135   explicit Resolver(grpc_combiner* combiner,
 136                     UniquePtr<ResultHandler> result_handler);
 137
 138   virtual ~Resolver();
 139
 140   /// Shuts down the resolver.
 141   virtual void ShutdownLocked() GRPC_ABSTRACT;
 142
 143   grpc_combiner* combiner() const { return combiner_; }
 144
 145   ResultHandler* result_handler() const { return result_handler_.get(); }
 146
 147  private:
 148   UniquePtr<ResultHandler> result_handler_;
 149   grpc_combiner* combiner_;
 150 };
 151
 152 }  // namespace grpc_core
 153
 154 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_H */