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/orphanable.h"
  29 #include "src/core/lib/gprpp/ref_counted_ptr.h"
  30 #include "src/core/lib/iomgr/iomgr.h"
  31 #include "src/core/lib/iomgr/work_serializer.h"
  32
  33 extern grpc_core::DebugOnlyTraceFlag grpc_trace_resolver_refcount;
  34
  35 namespace grpc_core {
  36
  37 /// Interface for name resolution.
  38 ///
  39 /// This interface is designed to support both push-based and pull-based
  40 /// mechanisms.  A push-based mechanism is one where the resolver will
  41 /// subscribe to updates for a given name, and the name service will
  42 /// proactively send new data to the resolver whenever the data associated
  43 /// with the name changes.  A pull-based mechanism is one where the resolver
  44 /// needs to query the name service again to get updated information (e.g.,
  45 /// DNS).
  46 ///
  47 /// Note: All methods with a "Locked" suffix must be called from the
  48 /// work_serializer passed to the constructor.
  49 class Resolver : public InternallyRefCounted<Resolver> {
  50  public:
  51   /// Results returned by the resolver.
  52   struct Result {
  53     ServerAddressList addresses;
  54     RefCountedPtr<ServiceConfig> service_config;
  55     grpc_error* service_config_error = GRPC_ERROR_NONE;
  56     const grpc_channel_args* args = nullptr;
  57
  58     // TODO(roth): Remove everything below once grpc_error and
  59     // grpc_channel_args are convert to copyable and movable C++ objects.
  60     Result() = default;
  61     ~Result();
  62     Result(const Result& other);
  63     Result(Result&& other) noexcept;
  64     Result& operator=(const Result& other);
  65     Result& operator=(Result&& other) noexcept;
  66   };
  67
  68   /// A proxy object used by the resolver to return results to the
  69   /// client channel.
  70   class ResultHandler {
  71    public:
  72     virtual ~ResultHandler() {}
  73
  74     /// Returns a result to the channel.
  75     /// Takes ownership of \a result.args.
  76     virtual void ReturnResult(Result result) = 0;  // NOLINT
  77
  78     /// Returns a transient error to the channel.
  79     /// If the resolver does not set the GRPC_ERROR_INT_GRPC_STATUS
  80     /// attribute on the error, calls will be failed with status UNKNOWN.
  81     virtual void ReturnError(grpc_error* error) = 0;
  82
  83     // TODO(yashkt): As part of the service config error handling
  84     // changes, add a method to parse the service config JSON string.
  85   };
  86
  87   // Not copyable nor movable.
  88   Resolver(const Resolver&) = delete;
  89   Resolver& operator=(const Resolver&) = delete;
  90   virtual ~Resolver() = default;
  91
  92   /// Starts resolving.
  93   virtual void StartLocked() = 0;
  94
  95   /// Asks the resolver to obtain an updated resolver result, if
  96   /// applicable.
  97   ///
  98   /// This is useful for pull-based implementations to decide when to
  99   /// re-resolve.  However, the implementation is not required to
 100   /// re-resolve immediately upon receiving this call; it may instead
 101   /// elect to delay based on some configured minimum time between
 102   /// queries, to avoid hammering the name service with queries.
 103   ///
 104   /// For push-based implementations, this may be a no-op.
 105   ///
 106   /// Note: Implementations must not invoke any method on the
 107   /// ResultHandler from within this call.
 108   virtual void RequestReresolutionLocked() {}
 109
 110   /// Resets the re-resolution backoff, if any.
 111   /// This needs to be implemented only by pull-based implementations;
 112   /// for push-based implementations, it will be a no-op.
 113   /// TODO(roth): Pull the backoff code out of resolver and into
 114   /// client_channel, so that it can be shared across resolver
 115   /// implementations.  At that point, this method can go away.
 116   virtual void ResetBackoffLocked() {}
 117
 118   // Note: This must be invoked while holding the work_serializer.
 119   void Orphan() override {
 120     ShutdownLocked();
 121     Unref();
 122   }
 123
 124  protected:
 125   Resolver(std::shared_ptr<WorkSerializer> work_serializer,
 126            std::unique_ptr<ResultHandler> result_handler);
 127
 128   /// Shuts down the resolver.
 129   virtual void ShutdownLocked() = 0;
 130
 131   std::shared_ptr<WorkSerializer> work_serializer() const {
 132     return work_serializer_;
 133   }
 134
 135   ResultHandler* result_handler() const { return result_handler_.get(); }
 136
 137  private:
 138   std::shared_ptr<WorkSerializer> work_serializer_;
 139   std::unique_ptr<ResultHandler> result_handler_;
 140 };
 141
 142 }  // namespace grpc_core
 143
 144 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_H */