3 * Copyright 2015 gRPC authors.
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
9 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 #ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_H
20 #define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_H
22 #include <grpc/support/port_platform.h>
24 #include <grpc/impl/codegen/grpc_types.h>
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"
34 extern grpc_core::DebugOnlyTraceFlag grpc_trace_resolver_refcount;
38 /// Interface for name resolution.
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.,
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> {
52 /// Results returned by the resolver.
54 ServerAddressList addresses;
55 RefCountedPtr<ServiceConfig> service_config;
56 grpc_error* service_config_error = GRPC_ERROR_NONE;
57 const grpc_channel_args* args = nullptr;
59 // TODO(roth): Remove everything below once grpc_error and
60 // grpc_channel_args are convert to copyable and movable C++ objects.
63 Result(const Result& other);
64 Result(Result&& other);
65 Result& operator=(const Result& other);
66 Result& operator=(Result&& other);
69 /// A proxy object used by the resolver to return results to the
73 virtual ~ResultHandler() {}
75 /// Returns a result to the channel.
76 /// Takes ownership of \a result.args.
77 virtual void ReturnResult(Result result) GRPC_ABSTRACT; // NOLINT
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;
84 // TODO(yashkt): As part of the service config error handling
85 // changes, add a method to parse the service config JSON string.
87 GRPC_ABSTRACT_BASE_CLASS
90 // Not copyable nor movable.
91 Resolver(const Resolver&) = delete;
92 Resolver& operator=(const Resolver&) = delete;
95 virtual void StartLocked() GRPC_ABSTRACT;
97 /// Asks the resolver to obtain an updated resolver result, if
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.
106 /// For push-based implementations, this may be a no-op.
108 /// Note: Implementations must not invoke any method on the
109 /// ResultHandler from within this call.
110 virtual void RequestReresolutionLocked() {}
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() {}
120 // Note: This must be invoked while holding the combiner.
121 void Orphan() override {
126 GRPC_ABSTRACT_BASE_CLASS
129 GRPC_ALLOW_CLASS_TO_USE_NON_PUBLIC_DELETE
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);
140 /// Shuts down the resolver.
141 virtual void ShutdownLocked() GRPC_ABSTRACT;
143 grpc_combiner* combiner() const { return combiner_; }
145 ResultHandler* result_handler() const { return result_handler_.get(); }
148 UniquePtr<ResultHandler> result_handler_;
149 grpc_combiner* combiner_;
152 } // namespace grpc_core
154 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_H */