GRPC Core  18.0.0
lb_policy.h
Go to the documentation of this file.
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_LB_POLICY_H
20 #define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H
21 
23 
24 #include <functional>
25 #include <iterator>
26 
27 #include "absl/status/status.h"
28 #include "absl/strings/string_view.h"
29 
38 
39 namespace grpc_core {
40 
42 
72 
80 // TODO(roth): Once we move to EventManager-based polling, remove the
81 // interested_parties() hooks from the API.
82 class LoadBalancingPolicy : public InternallyRefCounted<LoadBalancingPolicy> {
83  public:
84  // Represents backend metrics reported by the backend to the client.
97  std::map<absl::string_view, double> request_cost;
101  std::map<absl::string_view, double> utilization;
102  };
103 
106  class CallState {
107  public:
108  CallState() = default;
109  virtual ~CallState() = default;
110 
115  virtual void* Alloc(size_t size) = 0;
116 
119  // TODO(roth): Move this out of CallState, since it should not be
120  // accessible to the picker, only to the recv_trailing_metadata_ready
121  // callback. It should instead be in its own interface.
123 
129  virtual absl::string_view ExperimentalGetCallAttribute(const char* key) = 0;
130  };
131 
135  public:
136  class iterator
137  : public std::iterator<
138  std::input_iterator_tag,
139  std::pair<absl::string_view, absl::string_view>, // value_type
140  std::ptrdiff_t, // difference_type
141  std::pair<absl::string_view, absl::string_view>*, // pointer
142  std::pair<absl::string_view, absl::string_view>& // reference
143  > {
144  public:
145  iterator(const MetadataInterface* md, intptr_t handle)
146  : md_(md), handle_(handle) {}
148  handle_ = md_->IteratorHandleNext(handle_);
149  return *this;
150  }
151  bool operator==(iterator other) const {
152  return md_ == other.md_ && handle_ == other.handle_;
153  }
154  bool operator!=(iterator other) const { return !(*this == other); }
155  value_type operator*() const { return md_->IteratorHandleGet(handle_); }
156 
157  private:
158  friend class MetadataInterface;
159  const MetadataInterface* md_;
160  intptr_t handle_;
161  };
162 
163  virtual ~MetadataInterface() = default;
164 
170  virtual void Add(absl::string_view key, absl::string_view value) = 0;
171 
173  virtual iterator begin() const = 0;
174  virtual iterator end() const = 0;
175 
178  virtual iterator erase(iterator it) = 0;
179 
180  protected:
181  intptr_t GetIteratorHandle(const iterator& it) const { return it.handle_; }
182 
183  private:
184  friend class iterator;
185 
186  virtual intptr_t IteratorHandleNext(intptr_t handle) const = 0;
187  virtual std::pair<absl::string_view /*key*/, absl::string_view /*value */>
188  IteratorHandleGet(intptr_t handle) const = 0;
189  };
190 
192  struct PickArgs {
194  absl::string_view path;
203  };
204 
206  struct PickResult {
207  enum ResultType {
222  };
224 
228 
231  // TODO(roth): Replace this with something similar to grpc::Status,
232  // so that we don't expose grpc_error to this API.
234 
243  // TODO(roth): The arguments to this callback should be moved into a
244  // struct, so that we can later add new fields without breaking
245  // existing implementations.
246  std::function<void(grpc_error_handle, MetadataInterface*, CallState*)>
248  };
249 
265  public:
266  SubchannelPicker() = default;
267  virtual ~SubchannelPicker() = default;
268 
269  virtual PickResult Pick(PickArgs args) = 0;
270  };
271 
275  public:
276  ChannelControlHelper() = default;
277  virtual ~ChannelControlHelper() = default;
278 
281  ServerAddress address, const grpc_channel_args& args) = 0;
282 
286  const absl::Status& status,
287  std::unique_ptr<SubchannelPicker>) = 0;
288 
290  virtual void RequestReresolution() = 0;
291 
294  virtual void AddTraceEvent(TraceSeverity severity,
295  absl::string_view message) = 0;
296  };
297 
301  class Config : public RefCounted<Config> {
302  public:
303  ~Config() override = default;
304 
305  // Returns the load balancing policy name
306  virtual const char* name() const = 0;
307  };
308 
311  struct UpdateArgs {
314  const grpc_channel_args* args = nullptr;
315 
316  // TODO(roth): Remove everything below once channel args is
317  // converted to a copyable and movable C++ object.
318  UpdateArgs() = default;
320  UpdateArgs(const UpdateArgs& other);
321  UpdateArgs(UpdateArgs&& other) noexcept;
322  UpdateArgs& operator=(const UpdateArgs& other);
323  UpdateArgs& operator=(UpdateArgs&& other) noexcept;
324  };
325 
327  struct Args {
329  std::shared_ptr<WorkSerializer> work_serializer;
333  std::unique_ptr<ChannelControlHelper> channel_control_helper;
335  // TODO(roth): Find a better channel args representation for this API.
336  // TODO(roth): Clarify ownership semantics here -- currently, this
337  // does not take ownership of args, which is the opposite of how we
338  // handle them in UpdateArgs.
339  const grpc_channel_args* args = nullptr;
340  };
341 
342  explicit LoadBalancingPolicy(Args args, intptr_t initial_refcount = 1);
343  ~LoadBalancingPolicy() override;
344 
345  // Not copyable nor movable.
348 
350  virtual const char* name() const = 0;
351 
355  virtual void UpdateLocked(UpdateArgs) = 0; // NOLINT
356 
360  virtual void ExitIdleLocked() {}
361 
363  virtual void ResetBackoffLocked() = 0;
364 
365  grpc_pollset_set* interested_parties() const { return interested_parties_; }
366 
367  // Note: This must be invoked while holding the work_serializer.
368  void Orphan() override;
369 
370  // A picker that returns PICK_QUEUE for all picks.
371  // Also calls the parent LB policy's ExitIdleLocked() method when the
372  // first pick is seen.
373  class QueuePicker : public SubchannelPicker {
374  public:
376  : parent_(std::move(parent)) {}
377 
378  ~QueuePicker() override { parent_.reset(DEBUG_LOCATION, "QueuePicker"); }
379 
380  PickResult Pick(PickArgs args) override;
381 
382  private:
384  bool exit_idle_called_ = false;
385  };
386 
387  // A picker that returns PICK_TRANSIENT_FAILURE for all picks.
389  public:
392 
393  PickResult Pick(PickArgs args) override;
394 
395  private:
396  grpc_error_handle error_;
397  };
398 
399  protected:
400  std::shared_ptr<WorkSerializer> work_serializer() const {
401  return work_serializer_;
402  }
403 
404  // Note: LB policies MUST NOT call any method on the helper from their
405  // constructor.
407  return channel_control_helper_.get();
408  }
409 
411  virtual void ShutdownLocked() = 0;
412 
413  private:
415  std::shared_ptr<WorkSerializer> work_serializer_;
417  grpc_pollset_set* interested_parties_;
419  std::unique_ptr<ChannelControlHelper> channel_control_helper_;
420 };
421 
422 } // namespace grpc_core
423 
424 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H */
void grpc_channel_args_destroy(grpc_channel_args *a)
Destroy arguments created by grpc_channel_args_copy.
Definition: channel_args.cc:203
Definition: orphanable.h:76
Interface for accessing per-call state.
Definition: lb_policy.h:106
virtual absl::string_view ExperimentalGetCallAttribute(const char *key)=0
EXPERIMENTAL API.
virtual void * Alloc(size_t size)=0
Allocates memory associated with the call, which will be automatically freed when the call is complet...
virtual const BackendMetricData * GetBackendMetricData()=0
Returns the backend metric data returned by the server for the call, or null if no backend metric dat...
A proxy object implemented by the client channel and used by the LB policy to communicate with the ch...
Definition: lb_policy.h:274
virtual RefCountedPtr< SubchannelInterface > CreateSubchannel(ServerAddress address, const grpc_channel_args &args)=0
Creates a new subchannel with the specified channel args.
virtual void RequestReresolution()=0
Requests that the resolver re-resolve.
virtual void UpdateState(grpc_connectivity_state state, const absl::Status &status, std::unique_ptr< SubchannelPicker >)=0
Sets the connectivity state and returns a new picker to be used by the client channel.
TraceSeverity
Adds a trace message associated with the channel.
Definition: lb_policy.h:293
virtual void AddTraceEvent(TraceSeverity severity, absl::string_view message)=0
Interface for configuration data used by an LB policy implementation.
Definition: lb_policy.h:301
virtual const char * name() const =0
bool operator==(iterator other) const
Definition: lb_policy.h:151
bool operator!=(iterator other) const
Definition: lb_policy.h:154
iterator(const MetadataInterface *md, intptr_t handle)
Definition: lb_policy.h:145
value_type operator*() const
Definition: lb_policy.h:155
iterator & operator++()
Definition: lb_policy.h:147
Interface for accessing metadata.
Definition: lb_policy.h:134
virtual iterator erase(iterator it)=0
Removes the element pointed to by it.
virtual void Add(absl::string_view key, absl::string_view value)=0
Adds a key/value pair.
intptr_t GetIteratorHandle(const iterator &it) const
Definition: lb_policy.h:181
virtual iterator begin() const =0
Iteration interface.
QueuePicker(RefCountedPtr< LoadBalancingPolicy > parent)
Definition: lb_policy.h:375
PickResult Pick(PickArgs args) override
Definition: lb_policy.cc:98
~QueuePicker() override
Definition: lb_policy.h:378
A subchannel picker is the object used to pick the subchannel to use for a given call.
Definition: lb_policy.h:264
virtual PickResult Pick(PickArgs args)=0
~TransientFailurePicker() override
Definition: lb_policy.h:391
TransientFailurePicker(grpc_error_handle error)
Definition: lb_policy.h:390
PickResult Pick(PickArgs args) override
Definition: lb_policy.cc:138
Interface for load balancing policies.
Definition: lb_policy.h:82
virtual const char * name() const =0
Returns the name of the LB policy.
ChannelControlHelper * channel_control_helper() const
Definition: lb_policy.h:406
virtual void UpdateLocked(UpdateArgs)=0
Updates the policy with new data from the resolver.
virtual void ResetBackoffLocked()=0
Resets connection backoff.
grpc_pollset_set * interested_parties() const
Definition: lb_policy.h:365
void Orphan() override
Definition: lb_policy.cc:48
LoadBalancingPolicy & operator=(const LoadBalancingPolicy &)=delete
LoadBalancingPolicy(const LoadBalancingPolicy &)=delete
virtual void ExitIdleLocked()
Tries to enter a READY connectivity state.
Definition: lb_policy.h:360
virtual void ShutdownLocked()=0
Shuts down the policy.
~LoadBalancingPolicy() override
Definition: lb_policy.cc:44
LoadBalancingPolicy(Args args, intptr_t initial_refcount=1)
Definition: lb_policy.cc:34
std::shared_ptr< WorkSerializer > work_serializer() const
Definition: lb_policy.h:400
Definition: ref_counted.h:282
Definition: ref_counted_ptr.h:35
Definition: server_address.h:43
Definition: trace.h:61
#define DEBUG_LOCATION
Definition: debug_location.h:41
#define GRPC_ERROR_NONE
The following "special" errors can be propagated without allocating memory.
Definition: error.h:228
#define GRPC_ERROR_UNREF(err)
Definition: error.h:254
grpc_connectivity_state
Connectivity state of a channel.
Definition: connectivity_state.h:27
grpc_error_handle error
Definition: lame_client.cc:54
Round Robin Policy.
Definition: backend_metric.cc:26
absl::InlinedVector< ServerAddress, 1 > ServerAddressList
Definition: server_address.h:111
DebugOnlyTraceFlag grpc_trace_lb_policy_refcount(false, "lb_policy_refcount")
Definition: lb_policy.h:41
struct grpc_pollset_set grpc_pollset_set
Definition: pollset_set.h:31
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Args used to instantiate an LB policy.
Definition: lb_policy.h:327
std::unique_ptr< ChannelControlHelper > channel_control_helper
Channel control helper.
Definition: lb_policy.h:333
std::shared_ptr< WorkSerializer > work_serializer
The work_serializer under which all LB policy calls will be run.
Definition: lb_policy.h:329
const grpc_channel_args * args
Channel args.
Definition: lb_policy.h:339
std::map< absl::string_view, double > request_cost
Application-specific requests cost metrics.
Definition: lb_policy.h:97
uint64_t requests_per_second
Total requests per second being served by the backend.
Definition: lb_policy.h:93
double mem_utilization
Memory utilization expressed as a fraction of available memory resources.
Definition: lb_policy.h:90
double cpu_utilization
CPU utilization expressed as a fraction of available CPU resources.
Definition: lb_policy.h:87
std::map< absl::string_view, double > utilization
Application-specific resource utilization metrics.
Definition: lb_policy.h:101
Arguments used when picking a subchannel for a call.
Definition: lb_policy.h:192
absl::string_view path
The path of the call. Indicates the RPC service and method name.
Definition: lb_policy.h:194
MetadataInterface * initial_metadata
Initial metadata associated with the picking call.
Definition: lb_policy.h:199
CallState * call_state
An interface for accessing call state.
Definition: lb_policy.h:202
The result of picking a subchannel for a call.
Definition: lb_policy.h:206
grpc_error_handle error
Used only if type is PICK_FAILED.
Definition: lb_policy.h:233
ResultType type
Definition: lb_policy.h:223
std::function< void(grpc_error_handle, MetadataInterface *, CallState *)> recv_trailing_metadata_ready
Used only if type is PICK_COMPLETE.
Definition: lb_policy.h:247
RefCountedPtr< SubchannelInterface > subchannel
Used only if type is PICK_COMPLETE.
Definition: lb_policy.h:227
ResultType
Definition: lb_policy.h:207
@ PICK_COMPLETE
Pick complete.
Definition: lb_policy.h:211
@ PICK_FAILED
Pick failed.
Definition: lb_policy.h:221
@ PICK_QUEUE
Pick cannot be completed until something changes on the control plane.
Definition: lb_policy.h:215
Data passed to the UpdateLocked() method when new addresses and config are available.
Definition: lb_policy.h:311
ServerAddressList addresses
Definition: lb_policy.h:312
const grpc_channel_args * args
Definition: lb_policy.h:314
RefCountedPtr< Config > config
Definition: lb_policy.h:313
~UpdateArgs()
Definition: lb_policy.h:319
UpdateArgs & operator=(const UpdateArgs &other)
Definition: lb_policy.cc:71
Definition: error_internal.h:41